Skip to content

Capability 010: Documentation and Requirements

Status: Accepted

Context

Projects differ in how much they document and where they keep their requirements. A small project needs the Capability Specifications and nothing else. A commercial project may need ADRs with considered options, use cases, and business rules for readers outside the development team. Its requirements may live in an issue tracker. The workflow keeps the Working Documents the same in every case and adds Input and Derived Documents around them. This capability lets the developer choose the Documentation Mode (extent) and the Requirements Source and generates the files each choice needs.

References

Details

New fields of .repo.yaml, all at repository level:

Field Required Values Default
documentation no lean, extended lean
requirements no repo, external repo
tracker no URL of the issue list holding the Capability Specifications The issue list of repository on the forge of ci, filtered by the label capability; see below

Default of tracker, by ci:

ci Default of tracker
gitlab https://<repository>/-/issues/?label_name%5B%5D=capability
github https://<repository>/issues?q=is%3Aissue+label%3Acapability 
name: Example Shop
description: Online shop for spare parts.
repository: gitlab.com/example/shop
repoType: single
ci: gitlab
documentation: extended
requirements: external
artifacts:
  - name: shop
    ...

Files per setting, relative to the artifact directory and to the root of a mono-repository:

File Setting Owner Content
specs/inputs/README.md every Generator What an Input Document is and that it is translated into Capability Specifications
docs/README.md every Generator What belongs in docs/ and that the assistant works on it only when asked
specs/technical_design/ADRs/README.md lean Generator The lean ADR template, as today
specs/technical_design/ADRs/README.md extended Generator The MADR template
docs/use_cases/README.md extended Generator Use case template (Alistair Cockburn)
docs/business_rules/README.md extended Generator Business rule template
docs/architecture/README.md extended Generator Architecture description template with the 12 arc42 chapters. Chapters 3, 9, 10, and 12 link the system context, the ADRs, the Non-Functional Requirements, and the glossary
specs/capabilities/README.md repo Generator The Capability Specification template, as today
specs/capabilities/README.md external Generator That the Capability Specifications are issues, and where the issue template is
specs/capabilities/tracker.md external Generator The link of tracker
.gitlab/issue_templates/capability_specification.md every, ci: gitlab Generator The sections of the Capability Specification template
.github/ISSUE_TEMPLATE/capability_specification.yml every, ci: github Generator As for GitLab

Sections of the MADR template:

  • Status, Date, Decision-makers, Consulted, Informed
  • Context and Problem Statement
  • Decision Drivers
  • Considered Options
  • Decision Outcome, with Consequences and Confirmation
  • Pros and Cons of the Options
  • More Information

Functional Requirements

  1. repo update generates the files of Details for the values of documentation and requirements.
  2. The core rule tells the assistant to read an Input Document only when asked, and to translate it into Capability Specifications instead of implementing it.
  3. The core rule tells the assistant to read and change docs/ only when asked.
  4. With assistant claude, .claude/settings.json asks before every read, edit, and write below docs/.
  5. With requirements: external, the core rule tells the assistant that the Capability Specifications are issues in the tracker that specs/capabilities/tracker.md links, and that feature files and ADRs refer to the issue keys.
  6. Changing documentation or requirements and running repo update replaces the generator-owned files of Details. It changes no ADR, no Derived Document, and no Capability Specification.
  7. The docs site shows the documents below specs/, docs/, test/bdd/features/, and test/manual/.

Non-Functional Requirements

None.

Technical Requirements

None.

Error Handling

  1. A value of documentation or requirements outside Details is reported like any other invalid field (capability 001), naming the field and the permitted values.
  2. A tracker that is not an http or https URL is reported the same way.

Out of Scope

  • Deriving a Derived Document, which the developer does with or without the assistant
  • Issue templates for trackers other than GitLab and GitHub, such as Jira
  • Fetching issues from a tracker, e.g. an MCP server configuration
  • Converting existing ADRs to the other template
  • Links between the docs sites of a mono-repository's root and its artifacts
  • Copilot's access to docs/ beyond the core rule

Acceptance Criteria

  1. Go service without documentation: specs/technical_design/ADRs/README.md contains ## Alternatives and not Considered Options. There is no docs/use_cases/.
  2. Go service with documentation: extended: specs/technical_design/ADRs/README.md contains Decision Drivers, Considered Options, and Pros and Cons of the Options. docs/use_cases/README.md, docs/business_rules/README.md, and docs/architecture/README.md exist.
  3. Every profile with assistant claude: .claude/settings.json lists Read(docs/**), Edit(docs/**), and Write(docs/**) under ask.
  4. Every profile with assistant claude: .claude/rules/core.md names specs/inputs/ and docs/.
  5. Go service with requirements: external, ci: gitlab, and repository: gitlab.com/example/shop: specs/capabilities/tracker.md contains https://gitlab.com/example/shop/-/issues. .claude/rules/core.md names specs/capabilities/tracker.md.
  6. Same with tracker: https://example.atlassian.net/jira/software/projects/SHOP/issues: specs/capabilities/tracker.md contains that URL.
  7. Generated and committed Go service, requirements: external set, repo update: specs/capabilities/tracker.md exists.
  8. Go service with ci: gitlab: .gitlab/issue_templates/capability_specification.md contains every section heading of the Capability Specification template. Same with ci: github for .github/ISSUE_TEMPLATE/capability_specification.yml. Generated and committed Go service and mono-repository, the GitLab template deleted and committed, repo update: the template exists again.
  9. Generated Go service with an ADR committed, documentation: extended set, repo update: the ADR is unchanged. specs/technical_design/ADRs/README.md contains Considered Options.
  10. documentation: verbose: reported as invalid, naming documentation, lean, and extended. tracker: jira: reported as not an http or https URL.
  11. Go service with documentation: extended, a file added to docs/use_cases/: the docs site builds with mkdocs build --strict and contains a page for it, for specs/inputs/README.md, for each feature file, and for each manual test. Same for the combined docs site of a mono-repository, below each artifact, and for a file added to the root's docs/ (manual test test/manual/generated_docs_site.md).

Decisions

  1. Two settings at repository level, not per artifact. Who reads the documents and where requirements are kept is a property of the project. Consequence: all artifacts of a mono-repository share both settings.
  2. The ADR template follows documentation, without a setting of its own. Projects that expect a detailed rationale also expect the other Derived Documents. Consequence: MADR without Derived Documents needs a later capability, once a project asks for it.
  3. The generator writes templates for Derived Documents, never the documents themselves. Deriving is not deterministic and may need an assistant that is not available. A committed document stays readable without one. Consequence: a Derived Document can fall behind. The developer has it reviewed on request.
  4. docs/ is guarded by ask, not deny. deny would also block the assistant when the developer asks for a change in docs/. Consequence: the developer confirms every access. Copilot relies on the core rule alone.
  5. Issue templates follow ci, whatever requirements says. The template does not get in the way, and one rule keeps the generator simple. Consequence: a repository keeping its Capability Specifications as files also has the issue template.
  6. With requirements: external, feature files, manual tests, and ADRs stay in the repository. They are versioned with the code they verify or explain. Consequence: they refer to issue keys instead of capability numbers.
  7. tracker.md belongs to the generator; its link comes from tracker or from repository. A file of the developer would not appear when a repository switches to external later, since repo update writes such files only for a new module. GitLab and GitHub need no extra field. Consequence: a tracker other than the forge, such as Jira, needs tracker. The issue templates label every Capability Specification capability.