Whether the consequential technical decisions are written down — or whether the why lives only in people's heads and git archaeology.
Free & open · no signup · read-only — it ends by asking · nothing leaves your machine
You are working inside this repo. Mission: find the load-bearing technical decisions that shaped this codebase and check whether their reasoning is recorded — so a new engineer can learn why, not just what, without interrogating whoever remembers.
Read-only pass. Read docs, comments, commit history, and any ADRs; change nothing but the report file.
Phase 2 sweeps the codebase through every one of these, citing file and line for each finding.
the decisions that constrain everything else; are they recorded at all
do records capture reasoning and alternatives, not just the final choice
can a newcomer find why X was chosen without asking a person
records that describe a past the code no longer matches
do decisions note what would trigger revisiting them
the unwritten conventions that everyone is assumed to know
is there a lightweight practice for recording decisions, or none
One structured report at the repo root — or in reports/, if you keep one — the same shape every time, ready for a teammate — or the optional Studio — to act on.
Every Goal Prompt follows the same four steps, so results are consistent and repeatable — no matter which one you run.
Identify the choices that shape everything downstream.
Load-bearing choices — the decisions that constrain everything else.
Rank by cost-of-losing.
Create DECISIONS.md at repo root.
Copy it and paste it into your agent inside the repo you want checked.
Install the goal plugin once — two commands — then just type /goal:decision-records.
/plugin marketplace add GhostlyGawd/goal-prompts/plugin install goal@goal-promptsOr install only this Goal Prompt as /goal-decision-records:
curl -fsSL https://goal-prompts.vercel.app/install | BRIEF=97 shLet an agent fetch it mid-conversation, or pull the raw Goal Prompt by URL.
https://goal-prompts.vercel.app/raw/97.mdNothing hidden — this is the whole Goal Prompt, verbatim. Read it in a minute, edit it, or copy it as-is.
# Goal: Decision-Record Audit You are working inside this repo. Mission: find the load-bearing technical decisions that shaped this codebase and check whether their reasoning is recorded — so a new engineer can learn why, not just what, without interrogating whoever remembers. Read-only pass. Read docs, comments, commit history, and any ADRs; change nothing but the report file. ## Phase 1 — Surface the decisions - Identify the choices that shape everything downstream: architecture, framework, data model, key trade-offs. - For each, look for where the reasoning is recorded — a doc, an ADR, a PR description, or nowhere. - Note the "everyone just knows" rules that guide the code but live in no file. ## Phase 2 — Audit through 7 lenses 1. **Load-bearing choices** — the decisions that constrain everything else; are they recorded at all 2. **The why** — do records capture reasoning and alternatives, not just the final choice 3. **Discoverability** — can a newcomer find why X was chosen without asking a person 4. **Currency** — records that describe a past the code no longer matches 5. **Reversibility signals** — do decisions note what would trigger revisiting them 6. **Tribal knowledge** — the unwritten conventions that everyone is assumed to know 7. **Habit & format** — is there a lightweight practice for recording decisions, or none ## Phase 3 — Curate - Rank by cost-of-losing: the decisions whose rationale, if forgotten, would cause the most damage or rework. - For the top few, reconstruct the likely reasoning from the code and history. - Recommend a format light enough to actually get used. ## Phase 4 — Report Create `DECISIONS.md` at repo root: 1. **Undocumented decisions** — ranked by cost-of-losing the rationale 2. **Backfilled records** — a short ADR for the top few: context, choice, alternatives, consequences 3. **Tribal knowledge** — the unwritten rules that need a home 4. **The habit** — a lightweight ADR practice to adopt, with where records should live Start the report with today's date. If `DECISIONS.md` already exists from a previous run, read it first and lead with what changed since. ## Rules - Record the why and the alternatives; the what is already in the code - A decision only one person can explain is a bus-factor risk - No design decisions to trace in this repo? Say so in a one-paragraph null report and stop — a null result is a valid finding. - If a `reports/` directory exists at the repo root, write the report there instead of the root. - Before asking, present the top findings as a ranked list in plain words - Report only — end by asking which decisions to document first
reports/ directory exists at the repo root, write the report there instead of the root.Duplication, tangles, and dead patterns — mapped as interest paid vs principal owed, with a refactor sequence that pays for itself.
Walk clone → install → run → change → PR like a brand-new developer and log every stumble on the way to a first contribution.
Census the drifted colors, spacing, and duplicate components; propose the token set and migration order to unify them.
Can a coding agent work here? Entry files, one-command checks, discoverable conventions, and a mechanical definition of done — audited by attempting the work.