Governance Documentation

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

Document Selection

ADR Workflow

Use this checklist when creating an Architecture Decision Record:

- [ ] Read the template: templates/ADR.md
- [ ] Check docs/adr/ for the next available number
- [ ] Create file: docs/adr/ADR-NNNN-{short-title}.md
- [ ] Fill in all required sections
- [ ] Set status to "proposed"

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

Use this checklist when creating a Change Request:

- [ ] Read the template: templates/CR.md
- [ ] Check docs/cr/ for the next available number
- [ ] Create file: docs/cr/CR-NNNN-{short-title}.md
- [ ] Fill in all required sections
- [ ] Write acceptance criteria in Gherkin format
- [ ] Set status to "proposed"

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}