# Decisions > Single entry point for all architecture decision operations - Skill: `telefrek/decisions` (Agent Skill) - Install (CLI): `npx skillmds@latest add telefrek/decisions` - Raw SKILL.md: https://api.skillmd.com/api/skills/telefrek/decisions/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: telefrek (https://skillmd.com/u/telefrek) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/telefrek/decisions --- # /decisions [subcommand] [arguments] Single entry point for all architecture decision operations. ## Subcommands | Invocation | What it does | |------------|-------------| | `/decisions ""` | Query decisions in plain language | | `/decisions revisit ""` | Revisit decisions — find by topic or slug, understand why, check conditions, deliberate, optionally kick off a feature | | `/decisions defer "" [--until ]` | Park a topic for later | | `/decisions close "" [--reason ]` | Rule a topic out permanently | | `/decisions triage` | Review all deferred items and act on them | | `/decisions roadmap` | Cluster, classify, and prioritize the deferred backlog | | `/decisions list [--status ] [--search ]` | Browse and filter all decisions | | `/decisions explain ""` | Plain-language summary of a decision with KB context | | `/decisions candidates` | Review undocumented decision candidates from recent sessions | | `/decisions backfill [] [--limit N]` | Surface implicit decisions from source code. Path required for large projects (over backfill_file_threshold) | **Default (no subcommand):** if the first argument looks like a question rather than a subcommand name, treat it as `/decisions ""`. --- ## Pre-flight guard (all subcommands) Check that `.decisions/CLAUDE.md` exists. If not: ``` The decisions directory has not been initialised. Run /setup-vallorcine first. ``` Stop. --- ## decisions "" — natural language query Answers questions like: "What did we decide about caching?" "Have we ruled out GraphQL anywhere?" "What assumptions are we carrying about our database layer?" "Is there anything deferred that relates to auth?" No files are written. Read-only. Display opening header: ``` ─────────────────────────────────────────────── 🏛️ DECISIONS QUERY · "" ─────────────────────────────────────────────── ``` If no question was provided: ``` What would you like to know about your architecture decisions? e.g. "what did we decide about the database?" or "is there anything on caching?" ``` Wait for input, then proceed. ### Step 1 — Index scan Read `.decisions/CLAUDE.md` in full. Identify candidate slugs by matching the question against problem descriptions in all sections (Active, Recently Accepted, Deferred, Closed) and any keywords in Resume When or Reason columns. Read `.decisions//CLAUDE.md` for each candidate — one-line recommendation, status, last activity. Do NOT load full adr.md files yet. If no candidates found: ``` No decisions found matching "". The decisions store contains: confirmed · deferred · closed Try a broader term, or run /decisions revisit "" for a specific one. ``` Stop. ### Step 2 — Deep read (targeted) For each candidate where CLAUDE.md leaves the question unanswered, read only the relevant section of adr.md: - "What did we decide" → `## Decision` only - "Why did we choose X" → `## Rationale` only - "What assumptions" → `## Key Assumptions` + `## Conditions for Revision` - "What doesn't this solve" → `## What This Decision Does NOT Solve` - Deferred/closed stubs → read in full (they're short by design) Do not load `evaluation.md`, `constraints.md`, or `log.md` unless the user explicitly asks for scoring detail or decision history. ### Step 3 — Display the answer ``` RELEVANT DECISIONS — Decision: Date: Assumes: Revisit if: Resume when: Reason: Full record: .decisions//adr.md TANGENTS (set aside during deliberation) During , : "" — ─────────────────────────────────────────────── decision(s) found. Want more detail? /decisions revisit "" ─────────────────────────────────────────────── ``` **Quality rules:** - Lead with the conclusion — not background or preamble - If decisions conflict or constrain each other, note it - If something was explicitly closed, say so: "ruled out on because " - If genuinely uncertain (deferred with no context), say so --- ## decisions revisit "" — revisit and re-evaluate decisions Revisits existing decisions. Accepts a slug for a specific decision, a topic keyword, or a free text description to search across all accepted ADRs. Understands why the user wants to revisit before checking conditions or starting deliberation. May commission follow-up research if the user's concern points to a gap in the KB. Display opening header: ``` ─────────────────────────────────────────────── 🏛️ DECISIONS REVISIT ─────────────────────────────────────────────── ``` ### Step 1 — Find matching decisions The argument can be: - A **slug** — exact match against `.decisions//` - A **topic keyword** — matched against problem slugs, recommendation text, and constraint descriptions in the index - A **free text description** — matched against ADR content (problem statement, decision text, constraints, conditions for revision) Read `.decisions/CLAUDE.md` (and `history.md` if it exists). Find all accepted decisions that match the argument. For each match, read the `adr.md` to get the full decision and "Conditions for Revision" section. If no matches: "No accepted decisions match ''. Try /decisions list to browse all decisions." If one match: proceed directly to Step 2 with that decision. If multiple matches, present them using AskUserQuestion. Build the options dynamically — one option per match, plus an "All" option: ``` Found decisions matching "": ``` Use AskUserQuestion with: - One option per match, labeled ` — (accepted )` - A final option: `All` (description: "Revisit all matching decisions in order") ### Step 2 — Understand the motivation Before checking conditions or loading evaluation data, ask the user why they want to revisit. This conversation shapes the entire re-evaluation — a concern about performance at scale leads to different analysis than discovering a new algorithm. ``` ── ───────────────────────────────────── Decision: (accepted ) What's prompting you to revisit this? For example: • Constraints have changed (scale, resources, team, timeline) • You've seen or learned about an alternative approach • Implementation revealed unexpected problems • It's been a while and you want to sanity-check • You want to change direction regardless Or just describe what's on your mind. ``` Wait for the user's response. Use their answer to: 1. **Identify which constraint dimensions are affected** — if they mention performance, that maps to Scale or Accuracy. If they mention a new library, that's new research. If they say "it feels wrong," probe once for specifics before proceeding. 2. **Determine if follow-up research is needed** — if the user mentions a technology, approach, or paper that isn't in the KB, offer to commission research before re-evaluating: ``` I don't see in the KB. ``` Use AskUserQuestion: - "Research first" (description: "Run /research, then re-evaluate with new data") - "Proceed without" (description: "Continue with what we have") If "Research first": invoke `/research "" context: "decisions revisit: "` as a sub-agent, then continue to Step 3 with the new KB entry available. 3. **Determine if the user already knows the answer** — if they say "I want to change to X regardless," skip condition checking and go straight to Step 4 as an override. Append a `revisit-requested` log entry with the user's stated motivation. ### Step 3 — Check revision conditions Read: 1. `.decisions//adr.md` — "Conditions for Revision" section 2. `.decisions//constraints.md` — original constraints 3. `.decisions//evaluation.md` — candidate scoring Check each revision condition against the current state of the codebase and KB, **informed by the user's motivation from Step 2**: - **Scale thresholds** — read relevant source files or configs to check if thresholds have been crossed - **New research available** — check `.kb/` for entries added after the ADR's accepted date that are in the same topic/category as the ADR's candidates - **Time-based review** — check if the ADR's age exceeds any stated review interval - **Technology changes** — check if the ADR references technologies or constraints that may have evolved - **User's concern** — map their motivation to the relevant conditions and highlight which ones are affected Present the assessment: ``` Revision conditions for : ✓ — triggered: ✗ — not triggered: ? — unknown: Based on your concern about : ``` If no conditions are triggered AND the user's concern doesn't point to a gap: present this and offer to proceed anyway or confirm the decision still holds. ### Step 4 — Deliberate Load the full decision context: 1. `.decisions//adr.md` 2. `.decisions//constraints.md` 3. `.decisions//evaluation.md` 4. `.decisions//log.md` Branch based on the user's motivation and condition assessment: **Constraints changed:** ask for updated values, re-score changed dimensions, determine if recommendation changes. **New KB research:** read new subject file(s), score against current constraints, add to candidate pool, re-run comparison. Apply composite candidate detection (Step 4b2 from `/architect`) if the new research opens combination possibilities. **Implementation problems:** ask user to describe specifically, map to a constraint dimension, determine if ADR remains valid. **Override:** ask one question only — "Can you tell me why? I'll record it." Accept any reason or none. Proceed with override noted. **Sanity check (no specific concern):** present a brief summary of the decision, its constraints, and its conditions. Ask: "Does this still match your understanding of the problem? Anything feel off?" If the user confirms it's fine, mark as reviewed and move on. ### Step 5 — Present and confirm Present the outcome as a defence summary in chat (same format as `/architect` Step 7a) with one of these headers: - `[STILL VALID]` — recommendation holds; explain with KB evidence - `[REVISED]` — recommendation changes; explain what changed - `[OVERRIDE]` — user-directed change; state what changed and the reason Follow all deliberation chat rules from `/architect` Step 7b. ### Step 6 — Write confirmed outcome **Still valid (no change):** - Update `adr.md` frontmatter: `last_reviewed: YYYY-MM-DD` - Append `revisit-confirmed` log entry (includes user's motivation and "decision reaffirmed" outcome) **Revision:** 1. Mark current `adr.md`: `status: superseded`, `superseded_by: adr-v.md` 2. Write `adr-v.md` (from `/architect` ADR Template) 3. Append to `constraints.md` or `evaluation.md` as needed (`## Updates YYYY-MM-DD`) 4. Append `revision-confirmed` log entry 5. Update `.decisions//CLAUDE.md` ADR Version History 6. Update `.decisions/CLAUDE.md` master index After writing the outcome, check whether implementation work is needed: **If the decision was revised:** ``` ── Decision revised: ──────────────────── Previous: Revised: Reason: This revision may require implementation changes. feature — start /feature to implement the change (enters pipeline at planning — architecture context already loaded) later — note it and move on ``` **feature** — Generate a feature from the revision: - Slug: `revise-` (e.g., `revise-session-storage`) - Description: "Implement revised architecture decision: . Previous approach was . Changed because: ." - Create `.feature//` directory and write `brief.md` with: - The revision context (what changed, why) - The new ADR as the governing decision - Acceptance criteria derived from the ADR's "Implementation Guidance" section - Write `status.md` with stage set to `domains` (skip scoping — the brief is the ADR revision itself) - Write `domains.md` with the ADR already marked as `resolved` (it was just confirmed via deliberation) - Invoke `/feature-plan` as the next step — the feature enters the pipeline at planning, skipping scoping and domains since the architectural context is already established **later** — note in the review log and continue to next matched decision. **If the decision is still valid:** ``` ✓ Decision holds — reaffirmed . ``` Continue to next matched decision or finish. Every invocation produces at minimum a `revisit-requested` and a `revisit-confirmed` or `revision-confirmed` log entry. ### Step 7 — Summary ``` ─────────────────────────────────────────────── 🏛️ DECISIONS REVISIT complete Revisited: Still valid: Revised: Features started: ─────────────────────────────────────────────── ``` --- ## decisions defer "" [--until ] — park for later Writes a lightweight deferred stub without full evaluation. Create `.decisions//adr.md` with `status: deferred`: ```markdown --- problem: "" date: "" version: 1 status: "deferred" depends_on: [] --- # — Deferred ## Problem ## Why Deferred ## Resume When <--until condition, or "not specified"> ## What Is Known So Far ## Next Step Run `/architect ""` when ready to evaluate. ``` Append to `log.md`: ```markdown ## — deferred **Agent:** Architect Agent **Event:** deferred **Summary:** Marked deferred. Resume condition: . --- ``` Add a Deferred row to `.decisions/CLAUDE.md`. Update `.decisions//CLAUDE.md` with status `deferred`. Display: ``` ─────────────────────────────────────────────── 🏛️ Deferred: Resume when: Recorded in .decisions//adr.md To revisit: /architect "" To triage all deferred: /decisions triage ─────────────────────────────────────────────── ``` **Tangent capture during `/architect` deliberation:** if the user flags a topic as out-of-scope mid-deliberation, capture it the same way — brief acknowledgement, `tangent-captured` log entry on the parent problem, stub adr.md for the tangent, row in the Deferred (or Closed) section. Return to deliberation without re-presenting the full summary. See `/architect` Step 7b for full rules. --- ## decisions close "" [--reason ] — rule out permanently Writes a lightweight closed stub. Won't be raised again. Create `.decisions//adr.md` with `status: closed`: ```markdown --- problem: "" date: "" version: 1 status: "closed" --- # — Closed (Won't Pursue) ## Problem ## Decision **Will not pursue.** Explicitly ruled out — should not be raised again. ## Reason ## Context ## Conditions for Reopening ``` Append to `log.md` and add a Closed row to `.decisions/CLAUDE.md`. Display: ``` ─────────────────────────────────────────────── 🏛️ Closed: Reason: Will not be raised again. Recorded in .decisions//adr.md To reopen: /architect "" ─────────────────────────────────────────────── ``` --- ## decisions roadmap — cluster, classify, and prioritize the backlog Strategic planning pass across all deferred decisions. Clusters by theme, classifies each by effort, identifies dependencies, and writes a prioritized sequence. **Planning only — never executes work.** ### Step 1 — Run the scan ```bash bash .claude/scripts/decisions-scan.sh ``` Read the output at `.decisions/.roadmap-scan.md`. If zero deferred decisions: display "No deferred decisions to plan." Stop. ### Step 2 — Read problem statements For each deferred decision in the scan output, read the first ~30 lines of `.decisions//adr.md` to get the Problem and Resume When sections. **Do not read full ADRs** — you only need the problem scope, not the analysis context. ### Step 3 — Cluster by theme Group decisions into thematic clusters using: 1. **Parent ADR grouping** (from scan output — decisions sharing a parent are already related) 2. **Problem statement similarity** (merge parent groups that address the same domain — e.g., two parent groups both about encryption) Name each cluster descriptively (e.g., "Storage & Compression", "Encryption & Security", "Partitioning & Rebalancing"). ### Step 4 — Classify by effort For each decision, classify as: - **Gap-fill** — config option, single-method addition, validation check, thread-safety contract. 1-2 sessions. No architecture pass needed. Signals: problem mentions "config", "validation", "flag", "parameter", "contract"; scope is a single file or interface. - **Minor feature** — bounded new capability extending existing architecture. Brief `/architect` eval needed. 2-4 sessions. Signals: new type, new protocol extension, new API surface; scope is 2-3 files within one module. - **Full feature** — significant new architecture, multiple modules, new abstractions. Full `/architect` + `/feature` pipeline. 5+ sessions. Signals: problem mentions "protocol", "distributed", "consensus", "SDK", "new module"; has multiple viable approaches requiring evaluation. ### Step 5 — Identify dependencies Check for: 1. Decisions whose problem statement references another deferred decision 2. Decisions in the same cluster where one is clearly foundational (e.g., "connection-pooling" before "transport-traffic-priority") 3. Cross-cluster dependencies (e.g., networking must stabilize before distributed query features) ### Step 6 — Suggest ordering Order clusters by: 1. **Foundation first** — clusters that other clusters depend on 2. **Quick wins early** — clusters dominated by gap-fills 3. **Independence** — clusters with no external dependencies can be parallelized Within each cluster, order by: 1. Gap-fills before minor features before full features 2. Correctness risks and safety concerns first 3. Dependencies respected (A before B if B depends on A) Also identify: - **Immediate promotions** — decisions that are correctness/safety risks and should be addressed regardless of cluster ordering - **Duplicate merges** — decisions from different parents that describe the same problem (suggest merging into one ADR) - **Research suggestions** — full features where a `/research` pass would help before committing to `/architect` ### Step 7 — Write outputs **a. Roadmap document** — write `.decisions/roadmap.md`: ```markdown # Decisions Roadmap **Generated:** **Deferred:** decisions in clusters ## Summary gap-fill | minor feature | full feature ## Clusters (priority order) ### 1. ( decisions) **Gap-fills:** , , ... **Minor features:** , , ... **Full features:** , ... **Dependencies:** must precede because ... ### 2. ... ## Immediate Actions - **Promote:** — - **Merge:** + — same problem - **Research first:** — ## Suggested Sequence Phase 1: gap-fills (batch TDD pass) Phase 2: gap-fills + minor features ... ``` **b. Per-ADR metadata** — for each deferred decision where a dependency was identified, update the ADR's frontmatter to add: ```yaml depends_on: [""] ``` This allows `/architect` and `/feature` to surface dependencies when the user goes to work on a specific decision. Only add `depends_on` for concrete dependencies, not cluster-level ordering preferences. ### Step 8 — Present to user Display the roadmap summary and use AskUserQuestion: - "Start with Phase 1" — begin working through the first cluster - "Pick a cluster" — choose a specific cluster to focus on - "Create work group" (description: "Translate roadmap clusters into a work group for parallel execution") - "Done" — roadmap is written, user will return later If "Start with Phase 1" or "Pick a cluster": suggest the appropriate next command for each item (e.g., `/architect ""` for minor/full features, or a direct implementation reference for gap-fills). If "Create work group": proceed to Step 9. If "Done": stop. ### Step 9 — Create work group (if selected) Only runs if the user chose "Create work group" in Step 8. #### 9a — Choose group slug Use AskUserQuestion with options: - "decisions-backlog" (description: "Use the default group name") - Other — user provides a custom slug #### 9b — Create group directory and work.md Create `.work//` directory. Write `.work//work.md`: ```yaml --- group: goal: Resolve deferred decision backlog per roadmap status: active created: --- ``` ```markdown ## Goal Resolve deferred architecture decisions organized into thematic clusters per the roadmap at `.decisions/roadmap.md`. ## Scope ### In scope ### Out of scope - Decisions not in the deferred backlog - Implementation beyond ADR resolution (implementation follows via /work-start) ## Ordering Constraints ## Shared Interfaces None — decisions are documentation artifacts. ## Success Criteria - All deferred decisions in the roadmap are either accepted, closed, or re-deferred with updated conditions ``` #### 9c — Create WD files from clusters For each roadmap cluster (from the `## Clusters` section of `.decisions/roadmap.md`), write `.work//WD-.md`: ```yaml --- id: WD- title: group: status: DRAFT domains: [decisions] artifact_deps: - { type: adr, slug: "", required_status: accepted } ... produces: - { type: adr, slug: "" } ... --- ``` ```markdown ## Summary Decisions in this cluster: , , ... ## Acceptance Criteria - Each decision slug in this cluster has an accepted ADR or is explicitly closed/re-deferred - Implementation notes recorded for any that need follow-up features ## Implementation Notes **Effort classification:** - Gap-fills: - Minor features: - Full features: **Approach:** Process gap-fills first (direct TDD pass), then minor features (brief /architect evaluation), then full features (full /architect + /feature pipeline). ``` **Numbering:** WD-01, WD-02, etc. — in roadmap priority order (Phase 1 clusters first). **artifact_deps rules for cross-cluster dependencies:** - If the roadmap says "Cluster B depends on Cluster A because of ", then the WD for Cluster B gets `artifact_deps: [{type: adr, slug: "", required_status: accepted}]` pointing to the decision from Cluster A that must be resolved first. - Only add deps for concrete decision-level dependencies, not cluster-level ordering preferences. **produces rules:** - Each WD lists all decision slugs in its cluster as `produces: [{type: adr, slug: ""}]`. **Immediate promotions handling:** - Decisions flagged as "Immediate promotions" in the roadmap's `## Immediate Actions` section become a separate WD (e.g., "WD-01 — Immediate Promotions") with no `artifact_deps`. This WD is immediately READY. Its `produces` list contains the promoted slugs. Number it WD-01 so it sorts first. #### 9d — Run work-resolve.sh and update manifest Run: ```bash bash .claude/scripts/work-resolve.sh "" ``` Write `.work//manifest.md` using the same format as `/work-decompose` Step 6 (populate the Work Definitions table and Dependency Graph from the WD files). Add the group to `.work/CLAUDE.md` via the index helper, then refresh counts so the row reflects the WDs just created: ```bash bash .claude/scripts/work-index.sh add "" "" bash .claude/scripts/work-index.sh update "" ``` Do not hand-edit the table. #### 9e — Present result ``` Work group '' created from roadmap. work definitions ( ready, blocked) decisions across clusters Files: .work//work.md — scope .work//manifest.md — WD registry .work//WD-*.md — individual work definitions Next steps: /work-plan "" next — specify the first ready cluster /work-start "" next — implement a fully specified cluster /work-status "" — check readiness ``` Stop. --- ## decisions triage — review all deferred items Triages everything in the Deferred section of `.decisions/CLAUDE.md`. Display opening header: ``` ─────────────────────────────────────────────── 🏛️ DECISIONS TRIAGE ─────────────────────────────────────────────── ``` If the Deferred section is empty: ``` No deferred topics. Nothing to triage. ``` Stop. **Roadmap suggestion:** If 10+ deferred items exist, check whether `.decisions/roadmap.md` exists. If no roadmap (or roadmap is stale), use AskUserQuestion before proceeding: - "Run roadmap first" — cluster and prioritize before per-item triage - "Continue with triage" — process items one at a time as usual If the user picks "Run roadmap first": execute the roadmap subcommand (Step 1-8 above), then return here for triage. ### Step 1 — Build the triage list For each deferred item, read `.decisions//adr.md` to get full context. **Roadmap context:** If `.decisions/roadmap.md` exists, note each item's cluster and classification (gap-fill / minor / full) from the roadmap. Display this alongside the triage entry so the user sees the strategic context while triaging. Display: ``` Deferred topics ( total) ─────────────────────────────────────────────── [1] Deferred: ( days ago) Resume when: Depends on: Context: Source: <"standalone defer" | "tangent during: "> Roadmap: [2] ... ─────────────────────────────────────────────── ``` If a decision has `depends_on` entries that are still deferred (not yet confirmed), note this in the display: "blocked by: (still deferred)". This helps the user avoid evaluating decisions whose prerequisites aren't resolved yet. Process items one at a time. For each item, use AskUserQuestion with these options: - `Evaluate` (description: "Start /architect session for this topic") - `Close` (description: "Move to Closed, remove from Deferred") - `Update` (description: "Refresh resume condition or add context") - `Delete` (description: "Remove stub entirely") - `Skip` (description: "Leave as-is for now") ### Step 2 — Process choices **e — Evaluate:** invoke `/architect ""` as a sub-agent immediately. Remove the Deferred row after the Architect writes its ADR. **u — Update:** ask "what's changed?" Update adr.md Resume When and/or What Is Known So Far. Append `deferred-updated` to log.md. Refresh the Deferred row Resume When column. **c — Close:** ask for reason (optional). Update adr.md status to `closed`, update heading and sections. Append `closed` to log.md. Move row from Deferred to Closed in `.decisions/CLAUDE.md`. **d — Delete:** confirm before deleting. Remove `.decisions//` entirely. Remove Deferred row. No Closed row — deletion means it never needed recording. **s — Skip:** no changes. ### Step 3 — Summary ``` ─────────────────────────────────────────────── 🏛️ DECISIONS TRIAGE complete Evaluated: Updated: Closed: Deleted: Skipped: Deferred remaining: ─────────────────────────────────────────────── ``` If the Deferred section is now empty, add a `` comment to that section in `.decisions/CLAUDE.md`. Check total line count: if over 80 lines, archive oldest Recently Accepted rows to `history.md` (same crash-safe order as `/architect` Step 8: create history.md if needed → append row to history.md → remove row from CLAUDE.md). --- ## decisions list [--status ] [--search ] — browse all decisions Lists all decisions with filtering. Read-only — no files are written. Display opening header: ``` ─────────────────────────────────────────────── 🏛️ DECISIONS LIST ─────────────────────────────────────────────── ``` ### Step 1 — Load index Read `.decisions/CLAUDE.md` in full. Parse all sections: Active, Recently Accepted, Deferred, Closed. If `.decisions/history.md` exists, also read it (contains archived rows moved from the main index when it exceeded 80 lines). ### Step 2 — Apply filters **`--status `** — show only decisions matching this status. Values: - `accepted` or `confirmed` — confirmed ADRs - `draft` — draft ADRs (from backfill) - `deferred` — parked topics - `closed` — ruled out permanently - `all` — everything (default if no filter) **`--search `** — case-insensitive substring match against problem slug, problem description, and recommendation text. Multiple terms are AND-matched. If both flags are provided, apply both (intersection). ### Step 3 — Display ``` decisions found< (filtered: status=, search="")> STATUS SLUG DATE SUMMARY ──────── ────────────────────────── ───────── ─────────────────────── accepted rate-limiting-strategy 2026-03-10 Token bucket with Redis accepted storage-engine-choice 2026-03-08 LSM tree (jlsm-core) draft secondary-index-model 2026-03-16 Separate LSM per index deferred cache-invalidation 2026-03-12 Resume: after v2 launch closed graphql-api 2026-03-05 Ruled out: REST sufficient ──────────────────────────────────────────────── Total: accepted · draft · deferred · closed Details: /decisions revisit "" Query: /decisions "" ``` If no decisions match the filter: ``` No decisions found matching status=<, search="">. Total in store: ``` Sort order: accepted first (newest first), then draft, deferred, closed. --- ## decisions explain "" — plain-language summary Generates a readable summary of a decision with its supporting KB evidence. Useful for PR descriptions, onboarding, and team communication. Read-only. Display opening header: ``` ─────────────────────────────────────────────── 🏛️ DECISIONS EXPLAIN · ─────────────────────────────────────────────── ``` If slug not found: "No decision found for ''. Run /decisions list to see all decisions." ### Step 1 — Load Read in order: 1. `.decisions//adr.md` — the decision itself 2. `.decisions//constraints.md` — if it exists (what drove the decision) 3. `.decisions//evaluation.md` — if it exists (what was compared) For each KB link found in adr.md or evaluation.md: - Read only the `## Summary` or `## Key Parameters` section of the linked `.kb/` file — not the full entry. ### Step 2 — Generate summary Write a plain-language explanation structured as: ``` ── ───────────────────────────── STATUS: DATE: WHAT WE DECIDED <2-3 sentences in plain language. No jargon. Written for someone who has never seen the ADR. Lead with the conclusion.> WHY <2-3 sentences explaining the key constraints and tradeoffs that led here. Reference specific KB findings if they were influential.> WHAT WE CONSIDERED ✓ — ✗ — ✗ — ASSUMPTIONS - - SUPPORTING RESEARCH - .kb/ — - .kb/ — NOTE: This is a draft — the rationale above has not been through formal deliberation. Run /decisions revisit "" to formalize. NOTE: This topic is deferred. Resume condition: . ─────────────────────────────────────────────── ``` ### Step 3 — Offer next actions ``` Copy this summary into a PR description or share with your team. To revisit: /decisions revisit "" To see all: /decisions list ``` Stop. No files are written. --- ## decisions candidates — review discovered decision candidates Reviews undocumented decision candidates accumulated from recent sessions. Candidates are written to `.decisions/.decision-candidates` by a PostSessionEnd hook that scans conversation transcripts for decision-shaped language. Display opening header: ``` ─────────────────────────────────────────────── 🏛️ DECISIONS CANDIDATES ─────────────────────────────────────────────── ``` ### Candidate file format `.decisions/.decision-candidates` is an append-only file. Each candidate is a YAML-like block separated by `---`: ```yaml --- date: "2026-03-16" session: "" signal: "" context: "" suggested_problem: "" status: "new" --- ``` Status values: `new` (unreviewed), `processed` (acted on), `dismissed`. ### Step 1 — Load candidates Read `.decisions/.decision-candidates`. If it doesn't exist or has no `new` entries: ``` No undocumented decision candidates to review. Candidates are discovered automatically at the end of each session. ``` Stop. Filter to `status: new` entries only. ### Step 2 — Present candidates ``` ── candidates from recent sessions ──────── ``` Present each candidate one at a time: ``` ── of ───────────────────────────────── "" Session: Suggested: Use AskUserQuestion with these options: - `Decide` (description: "Start full /architect deliberation for this candidate") - `Draft` (description: "Write a partial ADR with rationale, to formalize later") - `Defer` (description: "Park for later with context") - `Dismiss` (description: "Not a real decision — mark as dismissed") Wait for user response. Process identically to `/decisions backfill` Step 4: - **decide** → invoke `/architect ""` as a sub-agent - **draft** → prompt for rationale, write draft ADR - **defer** → prompt for who/context, write deferred stub - **dismiss** → mark as dismissed in the candidates file After processing, update the candidate's status in `.decision-candidates` to `processed` or `dismissed`. ### Step 3 — Summary ``` ─────────────────────────────────────────────── 🏛️ DECISIONS CANDIDATES complete Decided: Drafted: Deferred: Dismissed: Remaining: ─────────────────────────────────────────────── ``` ### Discovery — how candidates are surfaced to users Candidates accumulate silently. The following pipeline commands check for `new` candidates in `.decisions/.decision-candidates` and display a notice if any exist: **`/feature-domains`** — after Step 2 (domain coverage display): ``` ℹ undocumented decision candidates from recent sessions. Run /decisions candidates to review. ``` **`/feature-resume`** — in the Step 2 status display: ``` ℹ decision candidates pending review. ``` **`/feature-resume --status`** — in the Current Blocker section (as informational, not a blocker): ``` Decision candidates: pending (/decisions candidates) ``` These notices are informational only — they never block the pipeline. ### PostSessionEnd hook — transcript scanning The hook script scans the current session transcript for decision-shaped language patterns: **Signal patterns** (regex-like, case-insensitive): - "let's go with ...", "let's use ..." - "I decided to ...", "we decided to ..." - "chose X over Y", "picked X instead of Y" - "the reason we're doing X is ..." - "going with X because ..." - "ruled out X", "not going to use X" **Filtering:** - Skip if the signal is inside a code block (implementation, not a decision) - Skip if it references an existing ADR slug from `.decisions/CLAUDE.md` - Skip if an identical signal already exists in `.decision-candidates` - Skip signals that are clearly about implementation details, not architecture ("let's use a for loop", "going with the simpler if/else") **What gets captured:** - The signal text (the decision-shaped quote) - Surrounding context (2-3 sentences before/after) - A suggested problem statement (inferred from the context) - The session date The hook script is installed as `.claude/hooks/post-session-decisions.sh`. It runs silently — no output to the user. It only appends to the candidates file. --- ## decisions backfill [] [--limit N] — retroactive decision extraction Scans archived features and source structure to surface implicit architectural decisions that were never documented as ADRs. Presents candidates one at a time for the user to decide, draft, defer, or dismiss. On projects with more than `backfill_file_threshold` source files (default 50, set in project-config.md), a `` argument is required to scope the scan. Display opening header: ``` ─────────────────────────────────────────────── 🏛️ DECISIONS BACKFILL ─────────────────────────────────────────────── ``` ### Step 0 — Parse arguments and size check - `` (optional): scope the source scan to this module/package path. Archived feature scan still runs (results are filtered to domains that relate to constructs in the scoped path). - `--limit N` (optional, default 5): max candidates to present this session. **Size check (before any scanning):** Read `.feature/project-config.md` for the source directory, language, and `Backfill file threshold` (default 50). Count source files using bash: ```bash find -type f \( -name "*." \) | wc -l ``` Use language from project-config to determine extensions: - Java: `*.java` - TypeScript/JavaScript: `*.ts *.tsx *.js *.jsx` - Python: `*.py` - Go: `*.go` - Rust: `*.rs` - Multiple languages: union of applicable extensions **If `` was provided:** skip the size check, proceed to Step 1. **If no `` and file count is under threshold:** proceed to Step 1. **If no `` and file count is at or over threshold:** require a path. List available top-level directories under the source root with file counts: ``` This project has ~ source files. To keep scan costs predictable, specify a module or package path: /decisions backfill / /decisions backfill / Available: // ( files) // ( files) // ( files) ... ``` Stop. Do not proceed without a path. ### Step 1 — Load dismissed list …(truncated)