Documentation Writing Skill

Executable BDD tests are produced by defining a strict artifact taxonomy and workflow that links requirements and design directly to executable `*_spec.spl` tests. This workflow reduces ambiguity by ensuring feature specs explicitly reference testing scenarios.

The software documentation workflow guides you from PLAN and REQUIREMENTS through FEATURE SPEC and into BDD TESTS and TEST RESULTS. It provides an end-to-end drafting sequence aligning architecture decisions and implementation details with testing.

Architecture decisions and requirement documents must be placed in specific repository locations defined by a strict artifact taxonomy. The Skill enforces where artifacts like research, NFR/SLO, architecture, ADR, design, spec, guides, tracking, and reports belong.

Writing `spec.md` is discouraged for feature specifications. You must adopt executable specs placed under the `test/` directory using the `*_spec.spl` format to ensure specifications are testable and traceable to requirements.

Architecture decision capture works by integrating ADRs into the document relationship model, linking them directly to feature specs and executable BDD tests. This ensures governance rules and design specifications remain aligned with testing scenarios throughout the workflow.

Research and design documents must adhere to prescribed formatting and writing standards defined by the artifact taxonomy. These governance rules ensure traceability across the workflow from initial research through to executable BDD test scenarios.