Decisions And Adrs

---
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 <NNN> — <short title>

Date: <YYYY-MM-DD>
Scope: strategic
Author: architect
Decided: [autonomously | with human input]
Revisit: [true | false]

## Context
## Decision
## Consequences
## Related
- Features: <links>
- Prior ADRs: <links or None>
- Superseded ADRs: <links or None>
```

`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-<slug>.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
---

# <Title>

## 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 |