decision-log

Files (1)

• SKILL.md

SKILL.md (first lines)

# decision-log

Maintains four artifacts in `docs/` for project tracking, layered from most-stable to most-volatile:

| File | Lifecycle | Purpose |
|---|---|---|
| `docs/VISION.md` | Immutable charter (amended only via a dated version bump + changelog, like an ADR) | The enduring **why / north star** that sits *above* STATUS and the ADRs. Authored once at Init; re-loaded every session; governs on conflict. |
| `docs/STATUS.md` | Living (rewritten when state changes) | One-page snapshot: current focus, what works, what's next, recent decisions/pivots |
| `docs/decisions/NNNN-title.md` | Immutable once accepted (status field can change) | One ADR per decision; new ADR supersedes old one to record pivots |
| `docs/log/YYYY-MM-DD.md` | Append-only (one file per session) | Chronological "what happened this session" |

**Philosophy:** purpose is stable and stated once (VISION, the north star nothing else may overwrite). Decisions and pivots get first-class storage (ADRs with explicit supersedes chain). Current state is one scannable page (STATUS). History is immutable session snapshots, not an ever-growing single log file.

**The VISION/STATUS line.** VISION holds only what would *not* change this quarter — the enduring purpose, who it's for, the non-negotiable principles, and the paths permanently off the table. STATUS holds everything tactical and current. The litmus test for any line: *"would this change this quarter? If yes, it belongs in STATUS, not VISION."* VISION governs on conflict; STATUS and logs may never silently overwrite it.

---

## Step 1 — Detect Mode

Check whether `docs/STATUS.md` AND `docs/decisions/` AND `docs/log/` exist at the project root.

- **All three exist** → **Update Mode** (Step 3)
- **Any missing** → **Init Mode** (Step 2)

**VISION backfill (independent of the mode check):** also check whether `docs/VISION.md` exists. If it does **not** — whether this is a fresh Init or a project scaffolded before VISION existed — run the **one-time VISION interview (Step 2f)** before the rest of the flow. VISION is authored exactly once; if it already exists, only *load* it (read it for context) and never silently rewrite it. Amendments go through Step 7 (Amend VISION).

Special sub-routines triggered by specific commands (run instead of the default flow):
- `/decide <title>` → jump to **Step 4 (New ADR)**
- `/supersede NNNN [optional new title]` → jump to **Step 5 (Supersede ADR)**
- `/log` → jump to **Step 6 (Session log only)**
- `/amend-vision` (or "update/amend the vision") → jump to **Step 7 (Amend VISION)**
- `/audit-vision` (or "review/audit the vision", "is my VISION any good") → jump to **Step 8 (Audit VISION)**

---

## Step 2 — Init Mode: Build From Existing Context

Goal: produce all three artifacts without interrogating the user. Pull from everything available before asking a single question.

### 2a. Gather context (silent reads, skip if missing)

- `README.md` — project overview, setup, architecture
- `CLAUDE.md` — project routing, conventions
- `HANDOFF.md` — if exists, often has audience-facing status
- `pyproject.toml` / `package.json` / `Cargo.toml` — project name + metadata
- `git log --oneline -50` — what's been built and when
- `git log --format="%H %ad %s" --date=short` — dated history for inferring sessions
- Any existing `docs/`, `research/`, `plans/`, or similar directories — prior decision artifacts to fold in
- The current working tree state via `git status --short`

### 2b. Detect retroactive decisions

Scan the gathered context for **decisions worth ADR-ing retroactively** — *not every choice*, only ones that:
- Reflect a deliberate trade-off (chose X over Y for a reason)
- Are referenced multiple times in the codebase or docs
- Captured an architecture or naming pivot (look for v1/v2/v3 doc pairs, "supersedes" language, "we used to do X but now do Y" notes)
- Were strategically load-bearing (mentioned in setup or onboarding)

**Cap retroactive ADRs at 5** unless the user asks for more. The point is to seed the pattern, not back-fill the whole project's history. Prefer the most architecturally significant decisions. Pivots especially valuable — if you find an obvious "we changed our minds" pair, capture both: the original as `status: superseded by ADR-NNNN` and the new direction as the superseding ADR.

### 2c. Draft STATUS.md

Use the **STATUS.md format** below. Pull current state from HANDOFF.md if it exists, README, recent commits. Be specific.

### 2d. Draft decisions/

Create:
- `docs/decisions/README.md` from the **decisions/README.md template** below
- `docs/decisions/0001-title.md` ... up to N retroactive ADRs

### 2e. Draft log/

- `docs/log/YYYY-MM-DD.md` for today (use today's date), capturing what's happening in *this* session (creating the decision-log structure itself)
- If the conversation history shows substantial prior work that wasn't logged, optionally create one entry for the most recent significant session (e.g., a recent git commit's date) — only if context is rich enough to be specific

### 2f. VISION interview — author the charter once (first-run gate)

This runs only when `docs/VISION.md` does **not** exist (per the Step 1 backfill check). It is the single creation trigger for the durable charter — an optional-to-write doc never gets written, so force authorship exactly once here, then load-only forever after.

First, try to draft VISION **from existing context** (README, CLAUDE.md, the project's own framing, STATUS's scope) without asking. Only if the enduring purpose isn't already clearly stated somewhere, ask **at most three** targeted questions in one message — don't interrogate:

1. **North star** — in one sentence, what is this project's enduring purpose / end-goal, independent of how it's built? (If the sentence would change this quarter, it's not the north star.)
2. **Who it's for** — who is worse off if this project doesn't exist?
3. **What it must always be** — the 3–7 non-negotiable principles future decisions must honor.

Draft `docs/VISION.md` from the answers (or from existing context) using the **VISION.md format** below. Populate the **Out of scope — do NOT revisit** block from any settled exclusions already visible (e.g. STATUS's "Out of scope" section, an ADR that closed a path) — this is what stops the agent from re-deciding things already off the table. Keep it ≤ ~1 page; resist roadmap creep.

After this, VISION is never re-interviewed — subsequent sessions only load it, and changes go through Step 7 (Amend VISION).

### 2h. LLMOps eval kernel — AI/LLM builds only (conditional)

Run this during the Init interview (alongside 2f, before the 2g draft) **only if the project builds on an LLM/AI API** — detect from deps (`anthropic`, `openai`, `@anthropic-ai/sdk`, `google-genai`, a `Claude API` import) or from the project's own framing. For an AI system, "correct" has to be defined *before* code, not discovered after — so surface this once at Init:

1. **Define "correct" up front.** Ask the user to commit to a small eval set — ~10 known-good cases + ~10 edge/failure cases — that encodes what a correct output looks like. Record it (an `evals/` YAML or a STATUS section) and **gate changes on it**: a change that regresses the eval set is not "done."
2. **Route uncertain outputs to a human.** Decide the confidence/abstain threshold below which the system defers to a person instead of guessing.
3. **Cost tracking.** A CostTracker (tokens + $ per call, logged) belongs in the *project's own code*, not this skill — flag it as a first-task so spend is visible from day one.

This is a prompt, not a build: decision-log records the decision (an ADR is a good home — e.g. "How we define and gate 'correct' for `<system>`"), while the eval set and CostTracker live in the project repo. Skip this sub-step entirely for non-AI projects. (It can also fire in Update Mode if an AI build *starts* mid-project — see Step 3b.)

### 2g. Show full draft + wait for approval

Present everything before writing:

```
---
Here's what I'll write to docs/ — review and approve before I create the files.

### docs/VISION.md   ← only when newly authored this run; omit if it already existed
[full draft]

### docs/STATUS.md
[full draft]

### docs/decisions/README.md
[full draft]

### docs/decisions/0001-<title>.md
[full draft]

From julianhernandez2155/claude-code-harness, MIT.

More from julianhernandez2155/claude-code-harness