---
name: project-decision-ledger
description: Use when a durable project, product, architecture, process, or implementation decision should be recorded, superseded, or reviewed. Maintains `.prd_plugin/state/decisions.json` or docs/decisions records with DEC-* or ARCH-DEC-* IDs, rationale, options, consequences, provenance, links, and registry updates.
---

# Project Decision Ledger

Use this skill to record decisions that future agents should not relitigate.

## Decision Record

Each decision should include:

1. ID: use `DEC-*` for standalone decisions or `ARCH-DEC-*` for architecture decisions.
2. Date.
3. Title.
4. Status: `proposed`, `accepted`, `superseded`, or `rejected`.
5. Context.
6. Decision.
7. Options considered when useful.
8. Consequences and tradeoffs.
9. Linked `BR-*`, `PRD-*`, `ARCH-*`, `IMP-*`, and `EV-*` IDs.
10. `supersedes` or `superseded_by` when replacing an earlier decision.
11. `created_by_agent` and `created_from_session` using `AGENT-*` and `SES-*`
    when the decision is agent-recorded.
12. `decided_by` (`autonomous`, `human_approved`, or `user_requested`) and
    `autonomy_tier` (the `automation.autonomy_level` in effect), so the autonomy
    trail is auditable. See `project-decision-policy`.

## Rules

- Use `prd_find`/`prd_get` to check existing decisions before creating one.
- Create through `prd_record_decision`; it allocates the ID and updates the
  registry atomically. Use `prd_link` for supported cross-record links.
- Fall back to careful state-file edits only when the validated tool authority
  is unavailable, then run `prd_validate` before relying on the record.
- Use `docs/decisions/` for longer standalone decision records.
- Do not store transient preferences as decisions.
- Do not silently edit accepted decisions to mean something different; add a superseding decision instead.
- Add or update `CHG-*` and `HLT-*` records when a decision materially changes
  project direction or resolves a health issue.
- Link `REQ-*` records when the decision accepts, rejects, or supersedes a
  request.

## Staleness Coverage

Apply the shared policy in `.prd_plugin/method/staleness-rules.md`.


Before recording or superseding a decision, check for stale `DEC-*`,
`ARCH-DEC-*`, `REQ-*`, `TRK-*`, and `HLT-*` records that the decision would
resolve or contradict. Supersede stale decisions explicitly instead of silently
editing their meaning.

## Review Checklist

- The decision has a clear reason.
- The linked IDs exist or are added in the same change.
- Consequences include at least one tradeoff when the decision narrows future options.
- Supersession is explicit.