Governance Documentation

Creates and manages governance documents: ADRs for architectural decisions, CRs for requirement changes.

Document Selection

| Need | Document | Guide | |------|----------|-------| | Technical/architectural decision | ADR | reference/adr-guide.md | | Requirement or scope change | CR | reference/cr-guide.md |

ADR Workflow

Documentation-only task. Creating an ADR is a documentation-only task. No code compilation, test execution, or linting is required.

Use this checklist when creating an Architecture Decision Record:

- [ ] Read the template: templates/ADR.md
- [ ] Check docs/adr/ for the next available number
- [ ] Capture current branch (`git rev-parse --abbrev-ref HEAD`) and commit (`git rev-parse --short HEAD`)
- [ ] Create file: docs/adr/ADR-NNNN-{short-title}.md
- [ ] Fill in all required sections (including source-branch and source-commit in frontmatter)
- [ ] Set status to "proposed"

Template frontmatter: The template file contains its own frontmatter (name: adr-template, description: Template for creating Architecture Decision Records (ADRs)., and metadata fields) that describe the template itself. Do not copy these values into created documents. Each ADR must have its own unique name and description reflecting the specific decision. Created ADR documents MUST omit the metadata.copyright and metadata.version frontmatter fields.

Strict requirements:

File naming: ADR-NNNN-{title}.md (four-digit number, lowercase, hyphens)
Initial status: proposed
Location: project's docs/adr/ folder

Flexible (adapt to context):

Level of detail in alternatives section
Number of consequences listed
Diagram inclusion (recommended for complex decisions)

CR Workflow

Documentation-only task. Creating a CR is a documentation-only task. No code compilation, test execution, or linting is required.

Use this checklist when creating a Change Request:

- [ ] Read the template: templates/CR.md
- [ ] Check docs/cr/ for the next available number
- [ ] Capture current branch (`git rev-parse --abbrev-ref HEAD`) and commit (`git rev-parse --short HEAD`)
- [ ] Create file: docs/cr/CR-NNNN-{short-title}.md
- [ ] Fill in all required sections (including source-branch and source-commit in frontmatter)
- [ ] Write acceptance criteria in Gherkin format
- [ ] Set status to "proposed"

Template frontmatter: The template file contains its own frontmatter (name: cr-template, description: Template for creating Change Requests (CRs)., and metadata fields) that describe the template itself. Do not copy these values into created documents. Each CR must have its own unique name and description reflecting the specific change request. Created CR documents MUST omit the metadata.copyright and metadata.version frontmatter fields.

Strict requirements:

File naming: CR-NNNN-{title}.md (four-digit number, lowercase, hyphens)
Initial status: proposed
Location: project's docs/cr/ folder
Acceptance criteria: Gherkin format (Given-When-Then)
Requirements keywords: RFC 2119 (MUST, SHOULD, MAY)

Flexible (adapt to context):

Document length (minimum 250 lines for complex changes)
Number of diagrams
Depth of impact assessment

Templates

ADR: templates/ADR.md
CR: templates/CR.md

Reference Guides

For detailed lifecycle information, best practices, and examples:

ADR Guide: reference/adr-guide.md
CR Guide: reference/cr-guide.md

Commit Message Format

Committing governance documents is the human's responsibility. When ready to commit, use these formats:

ADR: docs(adr): add ADR-NNNN {title}
CR: docs(cr): add CR-NNNN {title}