decision

Files (1)

• SKILL.md

SKILL.md (first lines)

# decision

Draft or extend a **decision record** — a living, evolving document that records a problem, the options considered, the reasoning, the chosen approach, and any open questions that may be revisited. Decision records are the canonical surface for long-lived architectural thinking in this workflow. Records start in `status: exploring` and graduate to `status: decided` when the decision is made.

The defining design principles of this skill are:

> **Batch every clarifying question into one up-front round, then run to completion uninterrupted.**
>
> **Persist findings to the decision record as the single source of truth. No parallel work-plan files. No duplicate task representations.**
>
> **Prefer extending an existing record to creating a new one. Duplication erodes the knowledge base.**

The user should be able to kick this off, answer a small batch of up-front questions, walk away, and return to a decision record they can review, edit, and then hand off to the `issue` skill for execution.

## How this fits the broader workflow

```
prompt
  │
  ▼
decision skill  →  decision record (with action items in canonical sections)   ← you are here
  │
  ▼
[HITL gate: human reviews, edits, greenlights the record]
  │
  ▼
issue       →  proposes tickets in chat → confirms with the user → creates tickets
  │
  ▼
Linear: LIN-NNN annotations written back into the record
```

This skill produces the artifact that `issue` consumes. The two skills share no runtime state — the decision record file is the only interface between them. After `decision` finishes, the human reviews and edits the record. Only then does `issue` read it.

## Context on the artifact

A decision record is a markdown file in `docs/decisions/` following the MADR-style convention:

- **Filename:** `nnnn-kebab-slug.md` where `nnnn` is the next serial number in the directory. Check `ls docs/decisions/ | sort -n | tail -1` before creating. New records start with the next available number.
- **Front matter:** YAML block with `title`, `tags` (lowercase, kebab-case where multi-word), `status` (`exploring | decided | superseded | deprecated`), `decision` (one-line TL;DR, filled when status becomes `decided`), `review_date` (YYYY-MM-DD), `related_to` (list of serial numbers), `supersedes` (serial number or empty).
- **Status Log:** table tracking lifecycle transitions with `Status | Date | Author | Related Tickets | Notes`.
- **Template sections:** `## Context`, `## Exploration`, `## Decision`, `## Consequences`, `## Confirmation`. Records may add custom sections like `## Open Questions`, `## Trigger Points`, `## Action items`, `## Upstream References`, `## Related Design Notes`.

New records start in `status: exploring` with the Decision, Consequences, and Confirmation sections empty or carrying `_No decision yet._`. When the decision is made (HITL), the status transitions to `decided` and those sections are populated.

### Slug generation protocol

The filename slug must be:
- **Clearly scoped** — captures the core concern, not a vague umbrella term
- **Reproducible** — different wordings of the same problem should converge on the same slug
- **General enough to survive reframing** — if the solution pivots, the slug should still apply
- **Stable** — once created, never renamed (the serial number is the stable reference anyway)

Heuristic: extract the 2–4 most distinguishing nouns/noun-phrases from the problem statement. Drop verbs, articles, and generic qualifiers. Join with hyphens. Examples:
- "Should we consolidate decisions/ and design-notes/?" → `decisions-dir-consolidation`
- "Which APM tool should we use?" → `select-apm`
- "How should we handle .envrc in repos?" → `envrc-template-pattern`

## Tools declared in allowed-tools

- Parallel subagents — investigate independent web research questions concurrently
- Web search and page fetching — direct research from the main agent when needed
- User clarification — the one-shot batched-clarification mechanism
- File search and reading — scope discovery across `docs/decisions/**`, `docs/TODO.md`, `CLAUDE.md`
- File writing and editing — creating new records and extending existing ones
- Linear MCP read tools — discovering related tickets and existing Linear docs
- Linear document saving (e.g. `save_document`) — for the strategy/process routing path

The `allowed-tools` declaration pre-approves tool *categories*. For scoped file writes, the user should configure Claude Code settings to pre-approve paths (see **Required grants** at the bottom).

## Phase 0 — Preflight

### Verify repo convention

- `docs/decisions/` exists and is writable. If not, stop and ask: "This repo doesn't have `docs/decisions/`. Bootstrap it from the kb convention, or bail?" Do not silently create the directory.
- Read the repo's `CLAUDE.md` / `AGENTS.md` at the root for project-specific HITL policies (especially around git and external dependencies).
- Note whether `docs/TODO.md` exists (it may not — the skill degrades gracefully).

### Permission preflight

Read the Claude Code settings files that may exist (in override order):

1. `~/.claude/settings.json`
2. `.claude/settings.json` (workspace)
3. `.claude/settings.local.json` (local override)

Check `permissions.allow` for entries matching `Write(docs/decisions/**)` and `Edit(docs/decisions/**)`. If either grant is missing, warn the user:

> The following permissions are not pre-approved in your Claude Code settings:
> - `Write(docs/decisions/**)` (needed to create new records)
> - `Edit(docs/decisions/**)` (needed to extend existing records)
>
> Each write will trigger a permission prompt, breaking the walk-away UX.
>
> To fix, add to your settings:
> ```jsonc
> { "permissions": { "allow": ["Write(docs/decisions/**)", "Edit(docs/decisions/**)"] } }
> ```

Offer two options to the user: **Proceed with prompts** / **Bail — I'll configure first**. If the grants are present, skip this entirely.

### Tool availability

If web search, page fetching, parallel subagents, or the Linear MCP tools are unavailable for policy or environment reasons, degrade gracefully: produce a note based on existing context only, and flag in the Status Log that web/Linear/subagent research was skipped.

## Phase 1 — Interpret and route

Restate the prompt in one or two sentences. Be explicit about the kind of design question it is.

Then apply the **routing test** from the asabina kb framework:

- **Code-adjacent** — architecture, implementation, tech stack, APIs, deployment, testing, tooling, developer experience, data model, security patterns → **repo** (`docs/decisions/`)
- **Strategy / process / team** — business strategy, positioning, marketing/GTM, team process, product prioritization rationale, cross-project org decisions → **Linear document** (saved via Linear's document API, e.g. `save_document`)
- **Ambiguous** → flag explicitly; ask in Phase 2 rather than silently defaulting

The kb's key test: *"Does this decision affect how code is written, deployed, or maintained?"* → repo. *"Is this about what to build or how to operate as a team?"* → Linear.

Write out the routing decision explicitly in your Phase 4 "locked decisions" commitment so the user can see and override.

From asabina-de/kb, CC-BY-4.0.

More from asabina-de/kb