@blundergoat/goat-flow
Version:
AI coding agent harness and local dashboard for Claude Code, OpenAI Codex, Google Antigravity, and GitHub Copilot - setup audits, guardrails, structured skills, deny hooks, and persistent learning loops.
124 lines (79 loc) • 5.27 kB
Markdown
# Decisions
Architectural Decision Records (ADRs) capture durable decisions that constrain future work. They are not task notes, TODO lists, bug reports, benchmark dumps, or confirmations that nothing changed.
> If the choice does not outlast the feature branch, it is not an ADR.
## Generated Index
`INDEX.md` in this directory is generated by `goat-flow index` - never edit it by hand. After adding, editing, renaming, or resolving entries, re-run `goat-flow index`; `goat-flow stats --check` fails while the index is stale.
## Automatic Capture Policy
Manual edits are normal: an explicit request to add or update a durable learning-loop entry means edit the Markdown in the correct directory. Programmatic automatic capture from terminal sessions, quality reports, PR reviews, or agent output is disabled unless `.goat-flow/config.yaml` explicitly sets `learning-loop.auto-capture.enabled: true` and a CLI-owned writer for that target exists. Prompts may suggest an ADR candidate, but automatic durable writes belong to CLI-owned code after opt-in.
Auto-capture candidates must follow Extract / Consolidate / Skip:
- Extract only when the item changes a future READ/SCOPE/ACT/VERIFY decision.
- Consolidate into an existing ADR when the same durable decision already exists.
- Skip raw tool output, successful smoke runs, UI/deploy churn, chain-of-thought, screenshots, raw JSON/HTML, duplicate dumps, and "I read the docs" summaries.
## When To Write An ADR
Write an ADR when the decision:
- changes the system structure, public contract, deployment model, data model, security model, or long-term workflow;
- constrains future implementation choices in a way another maintainer will need to understand;
- reverses, supersedes, or materially narrows an earlier decision;
- resolves a non-obvious trade-off with real evidence; or
- documents a durable exception that future agents might otherwise "fix" incorrectly.
Do not write an ADR for routine implementation details, temporary workarounds, benchmark traces, local debugging notes, or "we kept the existing behavior" confirmations.
## Wrong Home -> Right Home
| Note type | Correct home |
| --- | --- |
| Implementation TODO, checklist, milestone, or scoped plan | `.goat-flow/plans/` or the issue tracker |
| Reproducible hazard, trap, or recurring failure with measured evidence | `.goat-flow/learning-loop/footguns/` |
| Reusable takeaway from a completed fix or verification failure | `.goat-flow/learning-loop/lessons/` |
| Temporary scratch note, benchmark trace, raw command output, or local hypothesis | `.goat-flow/scratchpad/` |
| Backlog request, product question, or work that needs prioritisation | Linear/GitHub issue |
| Durable architecture, policy, contract, or trade-off decision | `.goat-flow/learning-loop/decisions/ADR-NNN-kebab-case-title.md` |
## Naming
ADR files must be named `ADR-NNN-kebab-case-title.md`, for example `ADR-001-cache-signature-policy.md`.
Allowed non-ADR files: `README.md` and `INDEX.md`.
Everything else in this directory is a stats failure. If a note cannot earn an ADR filename, route it using the table above.
## Required Structure
Every ADR must include:
```markdown
# ADR-NNN: Title
**Status:** Accepted
**Date:** YYYY-MM-DD
## Decision
What was decided. Be specific enough that someone can verify whether the codebase conforms.
## Context
Why this decision exists. Cite real incidents, constraints, measurements, or prior decisions.
## Failure Mode Comparison
| Option | What fails | Why rejected or accepted |
| --- | --- | --- |
| ... | ... | ... |
## Reversibility
Whether this is a one-way or two-way door, plus rollback or revisit triggers.
```
`## Context` may appear before `## Decision` if that reads better. Section order is not enforced.
At least one trade-off section is required:
- `## Consequences`
- `## Failure Mode Comparison`
- `## Reversibility`
Recommended metadata:
- `**Author(s):**`
- `**Ticket/Context:**`
- `**Updated:** YYYY-MM-DD` when amending an accepted ADR
## Status Values
- `Proposed` - under discussion, not yet binding
- `Accepted` - decision made, implementation may still be underway
- `Implemented` - decision is reflected in the codebase
- `Superseded by ADR-NNN` - replaced by a later decision
## Anti-Patterns
Do not create ADRs for:
- no-op confirmations, such as "we kept the existing threshold";
- TODOs disguised as decisions;
- workaround notes for a missing implementation;
- scoping notes that belong in a milestone file;
- benchmark traces without a durable decision;
- files missing the `ADR-NNN-...` filename, `**Status:**`, `**Date:**`, `## Context`, `## Decision`, or a trade-off section.
## Before Writing
Check all five before creating a file here:
- The decision will still matter after the current task closes.
- The decision constrains future choices or explains a non-obvious trade-off.
- The evidence is real and cited in the ADR.
- The file can honestly use an `ADR-NNN-kebab-case-title.md` name.
- The note does not belong in tasks, footguns, lessons, scratchpad, or the issue tracker.
If any check fails, do not write an ADR. Route the note to the correct home. If you are an AI agent and cannot decide, ask a human before creating a file in this directory.