desek/governance

Overview

This skill creates and manages governance documents for projects by generating Architecture Decision Records (ADRs) and Change Requests (CRs). It standardizes filenames, locations, status, and required sections so decisions and scope changes are documented consistently. Use it to capture technical decisions, rationale, alternatives, and formal requirement changes.

How this skill works

The skill inspects trigger keywords like ADR, architecture decision, CR, change request, governance, technical decision, and requirement change, then suggests or generates a properly formatted ADR or CR. It enforces strict rules such as four-digit, lowercase, hyphenated filenames, placement in docs/adr/ or docs/cr/, and initial status set to "proposed". For CRs it ensures acceptance criteria are written in Gherkin and recommends RFC 2119 keyword usage for requirements.

When to use it

• Documenting a new architectural choice or pattern that affects multiple teams
• Proposing a scope or requirement modification that needs traceability
• Formalizing decisions before substantial implementation effort
• Recording rationale and alternatives to aid future reviews or rollbacks
• Preparing governance artifacts for design reviews or audits

Best practices

• Follow the ADR and CR templates and place files under docs/adr/ or docs/cr/
• Use filenames like ADR-0001-short-title.md or CR-0002-short-title.md (four-digit, lowercase, hyphens)
• Set initial status to "proposed" and update status through lifecycle consistently
• Write CR acceptance criteria in Gherkin (Given-When-Then) and use RFC 2119 keywords for requirements
• Include consequences and diagrams for complex decisions but tailor detail to audience

Example use cases

• Choose a new service mesh and record trade-offs and migration plan in an ADR
• Change authentication requirements and submit a CR with Gherkin acceptance criteria
• Document deprecation of a legacy component with consequences and rollout steps
• Record a performance-oriented architecture pattern and attach diagrams for clarity
• Propose scope reduction for a release and track impacts via a CR