--- name: decisions-and-adrs description: "Use this skill whenever you create, write, modify, or statue an entry under `.decisions/` or `.adrs/`, or when you need to know the difference between a tactical DECISION and a strategic ADR, the two-zone frontmatter format of DECISION-NNN-*.md (zone author + zone review with `revisit`/`reviewed_by`/`reviewed_at`/`outcome` fields), the R2 strict rules under which green is allowed to author a tactical DECISION (scope=tactical, revisit=true at creation, necessary to unblock current task, DECISION-NNN referenced in code or commit message), or the R6 three-level defence around the `Authored-By:` commit trailer (pre-commit format, CI git-blame ↔ trailer cross-check, reviewer pass DoD sanity check). Also covers the architect's three statuing outcomes (confirm / reformulate / supersede) for tactical DECISIONS surfaced in RETRO.md `decisions_to_statue:` from the previous sprint, and the strategic ADR format. Loaded only by `architect` (writes strategic, statues tactical, both ADRs and DECISIONS), `green` (writes tactical DECISIONS under R2), and `sprint-planner` (lists pending tactical DECISIONS in `decisions_to_statue:` for next sprint's Wave 1 task). Other agents (PM, red, e2e-tester, reviewer, bug-detective) can read DECISION / ADR files without this skill — they just need the `## Relevant decisions` section of FEATURE.md to know which apply to a feature." --- # Decisions and ADRs The decision log mechanism for the agile-team-v2 workflow. Two distinct stores — `.decisions/` for tactical/strategic decisions with a review lifecycle, `.adrs/` for strategic Architecture Decision Records — plus the `Authored-By:` commit trailer that audits write authority. This skill is loaded only by the three agents that **write** to these stores: architect, green, sprint-planner. Other agents read DECISION/ADR files freely (they're public artifacts), but they don't need the format details, the R2 strict rules, or the statuing protocol. --- ## The two stores ### `.adrs/` — strategic, multi-feature, project-direction Architecture Decision Records. Format unchanged from v1. Strategic only — multi-feature impact, invariant changes, contracts that other features will depend on. The architect writes ADRs. ```markdown # ADR — Date: Scope: strategic Author: architect Decided: [autonomously | with human input] Revisit: [true | false] ## Context ## Decision ## Consequences ## Related - Features: - Prior ADRs: - Superseded ADRs: ``` `Revisit: true` indicates an autonomous decision under uncertainty — picked up at retro for human review. Tactical decisions go to `.decisions/`, **not** `.adrs/`. Do not mix. ### `.decisions/` — tactical or strategic, with two-zone frontmatter and review lifecycle The decision log distinct from strategic ADRs. The architect writes strategic DECISIONS directly. Green may write **tactical** DECISIONS during implementation under R2 strict rules (below). The architect **statues** every unstatued tactical DECISION at the start of the next sprint via a Wave 1 task placed by the sprint-planner. `.decisions/INDEX.md`: ```markdown | ID | Scope | Status | Title | Date | Author | |---------------|-----------|------------|----------------------------------|------------|-----------| | DECISION-042 | strategic | ACTIVE | session storage backend | 2026-04-15 | architect | | DECISION-051 | tactical | ACTIVE | session-id format choice | 2026-04-27 | green | ``` `.decisions/DECISION-NNN-.md` — **two-zone frontmatter**: ```yaml --- # Zone author — writeable at creation only id: DECISION-051 date: 2026-04-27 scope: tactical # tactical | strategic status: ACTIVE # ACTIVE | SUPERSEDED author: green # architect | green affects: [internal/auth/session.go] # Zone review — writeable by architect only, post-creation review: revisit: true # green sets true at creation; architect may flip false reviewed_by: null # null at creation; "architect" after statuing reviewed_at: null outcome: null # null | confirmed | reformulated | superseded --- # ## Question ## Decision ## Rationale ## Reformulated by architect (empty initially; filled at statue time if reformulating) ``` Every commit that creates or modifies anything under `.decisions/` carries the `Authored-By:` trailer (R6). --- ## R2 — Tactical DECISIONS by green Green may write a tactical DECISION when **all four** hold: 1. `scope: tactical` (never `strategic` — reserved for the architect). 2. `review.revisit: true` at creation (never `false` initially). 3. The decision is **necessary to unblock the current task** — not opportunistic. If green could finish the task without writing the DECISION, the DECISION should not be written. The architect picks up recurring patterns at retro time. 4. The DECISION-NNN is referenced in the code (a `// see DECISION-NNN` comment) or in the commit message body. Strategic DECISIONS are forbidden for green — they require the architect's authority. If green encounters what feels like a strategic decision in flight, the right move is a dispute (escalation type E in the dispute protocol) so the architect can decide and write the strategic DECISION. The sprint-planner surfaces each unstatued tactical DECISION in `RETRO.md decisions_to_statue:` at retro processing. The next sprint's plan starts with a Wave 1 task block for the architect to statue every entry. CI rejects a sprint that closes with `review.revisit: true` and `review.reviewed_by: null` on a DECISION older than one sprint window (`check.sh` enforces). --- ## The architect's three statuing outcomes For each unstatued tactical DECISION, the architect chooses exactly one outcome: ### Confirm The decision is sound as written. - `review.outcome: confirmed` - `review.reviewed_by: architect` - `review.reviewed_at: <YYYY-MM-DD>` - `review.revisit: false` - Body untouched. ### Reformulate The fundamental decision is right, but the phrasing was incomplete or misleading. - Same review fields as confirm with `outcome: reformulated`. - Rewrite `## Decision` and/or `## Rationale` to phrase it correctly. - Keep the same `id` and `date`. - Fill `## Reformulated by architect` explaining what was wrong and how it was fixed — this section is the audit trail. ### Supersede The decision is wrong. - On the original DECISION: - `status: SUPERSEDED` - `review.outcome: superseded` - `review.reviewed_by: architect` - `review.reviewed_at: <YYYY-MM-DD>` - Create a new `DECISION-MMM-<slug>.md` that explicitly supersedes this one (mention the superseded id in `## Rationale`). - Update `.decisions/INDEX.md` to reflect both: the original moves to `SUPERSEDED`, the new one is `ACTIVE`. ### Escalation: tactical → strategic If the decision's scope turned out larger than green originally judged (it affects multiple features or modifies an invariant assumed elsewhere), the architect may **promote** `scope: tactical` → `scope: strategic` during statuing. Note this in `## Reformulated by architect`. Optionally migrate the entry into `.adrs/` if it's genuinely a strategic ADR — in that case write a new ADR-NNN that consumes the DECISION's content, set the original DECISION's `status: SUPERSEDED` with `outcome: superseded`, and reference the new ADR. --- ## R6 — `Authored-By:` trailer and three-level defence The `Authored-By:` commit trailer audits write authority on `.decisions/` and on the `mechanical:` flag in FEATURE.md frontmatter. ### When the trailer is mandatory Every commit that: - Creates, modifies, or deletes any file under `.decisions/`. - Modifies the `mechanical:` field in any FEATURE.md frontmatter (architect-only field per R1). - Modifies the `review.reviewed_by` field in any DECISION. …**must** carry `Authored-By: <agent-id>` in the commit message body. Values: - `architect` — for the architect's writes (strategic DECISIONS, statuing tactical DECISIONS, modifying `mechanical:`). - `green` — for green's tactical DECISIONS only. ### Three-level defence 1. **Pre-commit hook** — verifies YAML zone format on `.decisions/` files. Blocks creation without `revisit: true`. Blocks zone-review modification without all four fields (`revisit`, `reviewed_by`, `reviewed_at`, `outcome`). Blocks zone-author modification post-creation. 2. **CI bloquante (`check.sh --mode ci`)** — `git blame` on `review.reviewed_by` modifications must correspond to a commit with `Authored-By: architect`. Mismatch → CI block. Same for `mechanical:` ↔ `Authored-By: architect`. 3. **Reviewer pass DoD** — sanity check final: iterates over commits in the sprint window touching `.decisions/`, verifies trailer ↔ zone modification consistency. Mismatch → blocking finding. This is **declarative**, not cryptographic. A buggy agent could write a false trailer. Mitigations: (a) agents follow their skill instructions, (b) `git blame` cross-checks the trailer against the commit identity, (c) the reviewer's pass DoD catches divergences before the sprint closes. The cost of a forged trailer is high (blocking finding at pass DoD, sprint cannot close). The cost of honesty is zero (just write the right trailer). Incentive is correctly aligned. Never bypass with `--no-verify`. --- ## Commit examples ### Architect creating a strategic DECISION ``` architect: DECISION-042 session storage backend choice Feature: auth-login Task: auth-login-decision-042 Authored-By: architect ``` ### Architect statuing a tactical DECISION (confirm) ``` architect: confirm DECISION-051 Feature: auth-login Task: auth-login-decision-review Authored-By: architect ``` ### Architect reformulating a tactical DECISION ``` architect: reformulate DECISION-051 — clarify session-id format Feature: auth-login Task: auth-login-decision-review Authored-By: architect ``` ### Architect superseding a tactical DECISION ``` architect: supersede DECISION-051 with DECISION-067 Feature: auth-login Task: auth-login-decision-review Authored-By: architect ``` ### Green writing a tactical DECISION during implementation ``` green: implement Authenticate + DECISION-051 (session-id format) Feature: auth-login Task: auth-login-T001-green Authored-By: green ``` ### Architect modifying mechanical: in FEATURE.md (during scaffolding) ``` architect: scaffold auth-login Feature: auth-login Task: auth-login-scaffold Authored-By: architect ``` The `mechanical:` field is set as part of the scaffolding commit; the trailer audits the authority. --- ## Anti-patterns - **Writing a strategic DECISION as green.** Forbidden. Raise a dispute (escalation type E) and let the architect handle it. - **Writing `revisit: false` at creation as green.** Forbidden. Tactical DECISIONS must be reviewed; `revisit: true` is mandatory at first write. - **Writing a tactical DECISION opportunistically.** If you can finish the task without the DECISION, don't write one. The architect picks up recurring patterns at retro. - **Editing an existing DECISION or ADR in place when superseding.** Always write a new entry that supersedes; never overwrite. The audit trail requires the original to remain readable. - **Skipping the `Authored-By:` trailer with `--no-verify`.** CI catches it. - **Modifying zone author after creation.** Author fields are immutable. If the metadata is wrong (e.g., wrong `affects:` list), supersede with a corrected DECISION. - **Mixing tactical and strategic in `.adrs/`.** `.adrs/` is strategic only. Tactical goes to `.decisions/`. - **Letting tactical DECISIONS pile up unstatued across sprints.** CI rejects a sprint that closes with unstatued tactical DECISIONS older than one sprint window. --- ## Quick reference table | What | Who writes | Trailer | Where | |-----------------------------------------------|----------------------------------|--------------------------|----------------------| | Strategic ADR | architect | Authored-By: architect (only on .decisions/ + mechanical: changes — ADRs alone don't require it) | `.adrs/NNN-*.md` | | Strategic DECISION | architect | Authored-By: architect | `.decisions/DECISION-NNN-*.md` | | Tactical DECISION (R2) | green | Authored-By: green | `.decisions/DECISION-NNN-*.md` | | Statuing a tactical DECISION (confirm/reformulate/supersede) | architect | Authored-By: architect | edits zone review of `.decisions/DECISION-NNN-*.md`; new DECISION on supersede | | Modifying `mechanical:` flag in FEATURE.md | architect | Authored-By: architect | `.features/<slug>/FEATURE.md` frontmatter |