auto-decision-capture

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->

# auto-decision-capture — proactive decision capture during sessions

This skill makes Claude an active participant in maintaining the project's
decision log. The user does not have to remember to write decisions, and
does not have to invoke a slash command. When evidence is in the
conversation, Claude writes; when evidence is weak, the end-of-session
Stop hook batches inferences for review.

## Core principle: signal-based, NOT turn-counted

There is no "wait N turns" rule. The threshold is **"is there textual
evidence?"**, not "have we waited long enough?". Every capture must
trace to a quote, an action, or a topic transition. No speculation
without a concrete signal.

## Signal taxonomy and confidence ladder

| Signal | Confidence | Write target | Write timing | Example |
|---|---|---|---|---|
| **Direct verbal marker (user)** | `explicit` | trusted (`build-loop-memory/projects/<project>/decisions/`) | immediately on user turn | "let's go with X" / "ship it" / "use Y" |
| **Choice converter** | `explicit` | trusted | immediately | Claude offered A/B/C; user said "B" |
| **Implementation declarative (agent)** | `explicit` | trusted | when stated in agent reasoning | "I'll use X for Y", "going with X over Y because Z", "implementing via X". For build-orchestrator subagents specifically — task-execution language IS a decision signal. |
| **Tradeoff statement** | `explicit` | trusted | when "X over Y because Z" appears | "extend YAML parser instead of changing test expectations" / "use X (Apache-2.0) over Y (GPL-3) because licensing" |
| **Threshold/parameter declaration with rationale** | `explicit` | trusted | when a numeric/named value is bound to reasoning | "cosine 0.85 because design ref §12 cites Mem0/Zep production consensus" / "default budget 25s leaves headroom on cold qwen3:8b" |
| **Default-value selection** | `confirmed` | trusted | when a default is declared | "default: `claude-opus-4-7` (current top model)" / "fall back to ollama on MLX failure" |
| **Action-confirmation (user)** | `confirmed` | trusted | after action accepted | Claude proposed → wrote code → user accepted without reverting |
| **Continuation pattern** | `confirmed` | trusted | when topic shifts past decision | proposal stood while conversation moved on |
| **Topic-coherent inference** | `inferred` | trusted, **overwriteable** | aggressive — written during session | Claude pattern-matched a position; user did not object but did not endorse |
| **Pure pattern-match from prior conversation** | `assumed` | trusted, **overwriteable** | aggressive — written during session | inferred from past decisions or memory |

**Note on agent-style language (build-orchestrator subagents, implementer subagents).** Task-execution language ("I'll add X", "extending Y", "default to Z") is just as much a decision signal as user-conversational language ("let's use Y"). Earlier versions of this skill under-captured agent decisions because the patterns were tuned only for user-Claude back-and-forth. The three middle rows above (Implementation declarative / Tradeoff / Threshold) are the explicit fix. **If you are reasoning as a subagent and you make any of those moves, capture it.**

**Tier 1 + 2 (explicit + confirmed) live captures during the session.**
Use `scripts/write_decision/__main__.py` directly with `--confidence explicit` or
`--confidence confirmed`. Set `--source auto-explicit` or
`--source auto-confirmed` so the capture is distinguishable from manual
human entries.

**Tier 3 + 4 (inferred + assumed) batch sweeps at session end** via the
Stop hook. The hook runs `scripts/scan_transcript_for_decisions.py`,
which calls a local LLM (`qwen3:8b-q4_K_M`) with Prompt C below. Tier 3
results land in `build-loop-memory/projects/<project>/decisions/_review/` for user promotion,
NOT in the trusted set.

You can also write tier-3 captures aggressively in-session if a
topic-coherent inference is strong. Old `inferred` of the same
`primary_tag + entity` is overwritten by the next signal — see
"Overwrite rules" below.

## Overwrite rules

Written into `write_decision.py`'s topic-identity supersession path
(`primary_tag + entity` is the topic key):

- Higher-confidence auto-supersedes lower (prior moves to `_history/<id>-vN.md`)
- Equal-confidence requires `--supersedes <id>` flag (refuse otherwise)
- Lower-confidence cannot displace higher (refused with exit 1)
- `inferred` and `assumed` captures are overwriteable by any newer signal of
  equal or higher confidence on the same topic

This is the safety mechanism that lets you capture aggressively without
poisoning the trusted set: a wrong inferred capture is corrected by the
next contradicting signal.

## What gets captured (positive evidence required)

- Decisions: choice + rationale + alternatives that were on the table + provenance
- Project-scoped constraints, preferences, conventions stated as durable
- Tooling/library/architecture choices with rationale

## What does NOT get captured

- Brainstorming that did not converge
- Questions the user asked Claude
- One-off corrections to a single response (these are feedback, not decisions)
- Anything Claude "thinks the user would want" without textual evidence
- Sensitive or volatile content where the user has not signaled durability

**No sensitivity-keyword filter.** Per project direction, capture any
decision the user makes regardless of topic. The user can revoke any
capture with `scripts/revoke_decision.py --id <id> --reason ...`.

## Tag selection — controlled vocabulary

Tags come from `write_decision.py`'s controlled vocabulary. New tags get the `proposed:`
prefix (e.g. `proposed:streaming-llm`), surfaced for promotion in the
next Phase 1 Assess. Do not invent tags outside this vocabulary —
vocabulary mismatch is the dominant retrieval failure mode.

## How to capture (live, during the session)

```bash
python3 scripts/write_decision/__main__.py \
  --workdir "$PWD" \
  --title "<one-line title>" \
  --decision "<one-sentence decision>" \
  --context "<1-3 sentences>" \
  --alternatives "<options considered>" \
  --consequences "<1-3 bullets>" \
  --tags "tooling,testing" \
  --primary-tag "testing" \
  --entity "<scope: project name or module>" \
  --confidence explicit \
  --source auto-explicit \
  --captured-turn-excerpt "<≤200 chars from the user's turn>" \
  --tool claude-code \
  --model claude-opus-4-7 \
  --task-category bugfix \
  --author auto
```

### v2 metadata fields (skill-driven captures)

Frontmatter v2 (added 2026-05-04, design §15) attaches five required
fields and four optional fields to every decision. The writer applies
sensible defaults so legacy callers still work, but skill-driven
captures should set these explicitly when the signal is clear:

From tyroneross/build-loop, Apache-2.0.

More from tyroneross/build-loop