Agent-Skills.md

Agent Skills: Decision Log

Record or search technical decisions in a persistent SQLite database. Default mode records the most recent decision from conversation with alternatives and reasoning. Use with "search" argument to query past decisions.

UncategorizedID: hairihou/dotfiles/decision-log

Repository

hairihou/dotfiles
hairihou

Install this agent skill to your local

pnpm dlx add-skill https://github.com/hairihou/dotfiles/tree/HEAD/src/.config/claude/skills/decision-log

Skill Files

Browse the full folder contents for decision-log.

Download Skill

Loading file tree…

src/.config/claude/skills/decision-log/SKILL.md

Skill Metadata

Name
decision-log
Description
Record design/architecture/tooling decisions with alternatives, reasoning, and outcomes for retrospective review. Use when discussing trade-offs, comparing alternatives, finalizing a decision, recalling past decisions, or asking "why did we choose X?"

Decision Log

Persistent decision record with alternatives and reasoning. Enables retrospective review of past choices and their outcomes.

Context

  • Date: !date "+%Y%m%d"
  • Repository: !git rev-parse --show-toplevel (use basename only, e.g., dotfiles not the full path)
  • DB: !python ${CLAUDE_SKILL_DIR}/scripts/db.py init
  • Summary: !python ${CLAUDE_SKILL_DIR}/scripts/db.py summary

Script: ${CLAUDE_SKILL_DIR}/scripts/db.py

Mode: Record (default)

Use when no argument is provided or argument is not "search".

Steps

  1. Analyze: Review conversation for the most recent decision where alternatives were considered

  2. Extract: Identify topic, chosen approach, alternatives, reasoning, consequences, confidence, and reevaluation trigger

  3. Confirm: Use AskUserQuestion to present the decision and get approval. Format the question as:

    Decision Record
- Date: <date>
- Repository: <repo-basename>
- Topic: <short-label>
- Chosen: <approach>
- Alternatives: <other options considered>
- Reasoning: <why this was chosen>
- Consequences: <expected impact — what happens as a result>
- Confidence: <high|medium|low>
- Reevaluate when: <condition that should trigger revisiting this decision>

    Suggested responses: ["OK", "Revise"] If the user wants changes, revise and re-confirm.

  4. Insert:

    python ${CLAUDE_SKILL_DIR}/scripts/db.py insert '<date>' '<repo>' '<topic>' '<chosen>' '<alternatives>' '<reasoning>' --consequences '<consequences>' --confidence <level> --reevaluate-when '<condition>'

    Omit --consequences, --confidence, or --reevaluate-when if not applicable.

  5. The script prints the inserted record.

Mode: Supersede

Use when argument starts with "supersede". Never edit an accepted decision — supersede it instead.

Steps

  1. Find the decision to supersede via search (detail <id> for full context)

  2. Follow the same Extract → Confirm flow as Record mode, but also show which decision is being superseded and why

  3. Insert:

    python ${CLAUDE_SKILL_DIR}/scripts/db.py supersede <old-id> '<date>' '<repo>' '<topic>' '<chosen>' '<alternatives>' '<reasoning>' --consequences '<consequences>' --confidence <level> --reevaluate-when '<condition>'

  4. The script marks the old decision as superseded and links it to the new one.

Mode: Search

Use when argument contains "search".

Steps

  1. Parse intent: Understand what the user is looking for from conversation context
  2. Build and run query: Use only these documented flags — do not invent others (e.g., no --head, --limit, --recent). For "recent decisions", pass --from <YYYYMMDD> with a date cutoff.
    • search filters: --repo, --match, --from, --to, --status
    • Other subcommands: detail <id>, update-outcome <id> '<outcome>'
    • If unsure, run python ${CLAUDE_SKILL_DIR}/scripts/db.py search --help first
  3. Format: Present results in a readable format

Guidelines

  • chosen/alternatives/reasoning: Write in plain English, concise but complete
  • topic: Use kebab-case short labels (e.g., db-architecture, cache-strategy, skill-trigger-method)
  • confidence: high = well-researched with clear winner, medium = reasonable choice but alternatives are close, low = best guess under uncertainty or time pressure
  • consequences: What happens as a result of this decision — operational impact, trade-offs accepted, follow-up work required. Distinct from reasoning (why) — consequences describe what follows (then what)
  • reevaluate_when: The specific condition that should trigger revisiting this decision (e.g., "team grows past 5 people", "latency exceeds 200ms", "library reaches v2.0")
  • outcome: Update later via search mode when results are known
  • supersede: When a decision changes, never modify the original — use supersede mode to preserve history
  • Escape single quotes in shell arguments: 'it'\''s'

Common Mistakes

  • Writing a sentence as topic instead of a kebab-case label (e.g., We decided to use PostgreSQL → database-selection)
  • Recording only the chosen approach without alternatives — the value is in knowing what was rejected and why
  • Recording trivial decisions (variable naming, minor formatting) — only record decisions where alternatives had meaningful trade-offs
  • Confusing reasoning with consequences: reasoning = "Redis is faster for our access pattern" / consequences = "adds operational dependency on Redis, need monitoring"
  • Setting confidence to high by default — be honest about uncertainty