spec-driver — Prompts
This file quotes verbatim the most important prompt files from the spec-driver repository.
Excerpt 1: using-spec-driver SKILL.md (mandatory routing skill)
Source: .spec-driver/skills/using-spec-driver/SKILL.md
---
name: using-spec-driver
description: Mandatory routing skill for ANY substantive work in a spec-driver project. Choose the governing skill before acting, and do not start implementation until the required delta/design/plan/phase artefacts exist.
---
You MUST choose the governing workflow skill before doing substantive work.
This skill is not optional process fluff. It is the routing layer for work in a
spec-driver repo.
If there is a reasonable chance that another spec-driver skill governs the
task, you MUST route through that skill before proceeding.
Do not respond, explore, inspect files, run commands, or start implementation
until you have decided which skill governs the task.
Do not rationalize your way around this.
If you skip routing because the task feels familiar, simple, urgent, or
"probably fine", you are doing it wrong.
Red-flag thoughts:
- "I can just inspect files first."
- "I already know the command shape."
- "This is small enough that I do not need workflow routing."
- "I will gather context first and decide later."
Those are routing failures. Stop and choose the governing skill.
Technique demonstrated: Anti-reasoning attack. The prompt explicitly names the mental shortcuts an LLM uses to rationalize skipping governance ("familiar", "small", "urgent") and labels them as failure modes. Forces the agent into a declared routing decision before any action.
Excerpt 2: retrieving-memory SKILL.md (mandatory context retrieval)
Source: .spec-driver/skills/retrieving-memory/SKILL.md
---
name: retrieving-memory
description: |
Invoke this skill before making non-trivial assumptions in a large codebase. Mandatory triggers: (1) you are about to modify a subsystem you have not touched in this run; (2) you are about to run, change, or suggest a command pipeline (tests, builds, releases, migrations); (3) you see conflicting cues in code/docs; (4) you are asked "what is the right way here?"; (5) you are debugging a recurring failure mode; (6) you are about to answer with "probably/usually/likely".
Default rule: if you cannot cite a source-of-truth file/doc/ADR/SPEC from the repo, you must consult memories first and then proceed.
---
Retrieval procedure (fast → thorough):
1. Contextual list (preferred):
- Use scope matching to get the most relevant memories:
`spec-driver list memories -p <path>... -c "<command tokens>" --match-tag <tag>...`
- Before working on a specific subsystem, build this query from the concrete
files you expect to read or edit first. Memories with `scope.globs` still
match those `-p` paths, so you do not need a separate glob flag.
- For planned code changes, prefer at least one exact file path plus the
command context you are about to run. Example:
`spec-driver list memories -p supekku/scripts/lib/skills/sync.py -c "uv run pytest" --match-tag skills`
Decision framework (what to trust):
- Prefer memories with higher `priority.severity`, higher `priority.weight`, higher scope specificity, and more recent `verified/updated` (the list ordering already encodes this).
- If a memory lacks `provenance.sources` for a claim, treat it as advisory only and verify against code/docs before acting.
- If retrieved memories disagree, do not "average"; escalate to maintenance (update/supersede) before proceeding with consequential changes.
Output discipline:
- When responding or planning, cite the relevant memory IDs and their linked sources (paths/ADRs/specs). If you cannot, retrieve again with tighter `--path/--command/--match-tag` until you can.
- **Staleness awareness** — when presenting a retrieved memory, surface its
verification state qualitatively:
- No `verified_sha`: "this memory has not been attested against the codebase"
- High staleness (many commits since attestation): "many commits have affected
its scope since last attestation — treat with caution"
Technique demonstrated: Mandatory trigger list with enumerated conditions. Turns the agent's use of hedging language ("probably", "usually", "likely") into a circuit-breaker that forces memory retrieval before proceeding.
Excerpt 3: execute-phase SKILL.md (mandatory implementation skill)
Source: .spec-driver/skills/execute-phase/SKILL.md
---
name: execute-phase
description: Mandatory execution skill for any delta/IP implementation phase. Use it before code changes, move the owning delta to in-progress, keep notes current, reconcile structured execution docs, and surface blockers early.
---
This skill is mandatory for implementation work under a delta or implementation
plan.
Do not start coding, editing tests, or updating implementation docs for a
delta/IP phase until you have entered through `/execute-phase`.
If the delta still says `draft`, that is not harmless bookkeeping. Change it to
`in-progress` before implementation continues so the lifecycle truth matches the
actual state of work.
Process:
1. Confirm entry criteria are met for the active phase.
2. Read DR + IP + phase sheet before coding and use `/preflight` to surface
confirmed inputs, assumptions, unresolved questions, and tensions before
implementation.
3. Identify the concrete files or components you expect to touch first and run
`/retrieving-memory` against those paths before deep reading or editing so
any `scope.globs` gotchas or patterns surface early.
4. Ensure the owning delta frontmatter says `status: in-progress` before implementation work proceeds. If it still says `draft`, update it first.
5. Implement phase tasks (code/tests/docs) in small coherent units.
6. After each meaningful unit, run `/notes`.
7. If that unit produced a durable gotcha, pattern, or subsystem fact worth
future retrieval, run `/capturing-memory` or `/maintaining-memory` before
moving on.
Technique demonstrated: Lifecycle truth enforcement. The skill frames a "draft" status as "not harmless bookkeeping" — it forces agents to treat artefact state as authoritative ground truth, not a label to update lazily. Every implementation step is coupled to a memory/notes action.
Excerpt 4: preflight SKILL.md (bounded research skill)
Source: .spec-driver/skills/preflight/SKILL.md (first 50 lines)
---
name: preflight
description: Use after routing has already happened, when the next step is bounded up-front research...
---
This is NOT the first routing skill for work in a spec-driver repo.
If you have not already chosen the governing skill path, stop and use
`/using-spec-driver` first.
You're about to begin work on something: $ARGUMENTS
First: you need to understand what it entails. Your immediate task is to
correctly decide how much effort to spend on this preliminary research.
Too little is as bad as too much. You must estimate where the goldilocks zone is,
and arrive with maximum tokens intact.
If you chase the questions which arise as you go, you'll disappear like a
helium balloon into the open sky.
Instead:
1. Read the material in front of you
2. Take stock of relevant `/retrieving-memories` and `/doctrine`
3. Confirm your stopping conditions before you expand the search
4. Decide **up front**, out loud:
- what, concretely, you need to know.
- when, concretely, you will stop even if you don't have all the answers.
7. Before declaring readiness, produce a critical assessment with these headings:
- confirmed inputs
- assumptions you would carry into the next step
- unresolved questions, risks, or dependencies
- tensions or ambiguities (including any apparent contradictions between artifacts, or design & implementation surface)
Technique demonstrated: Token budget awareness baked into research direction. The "helium balloon" metaphor is a memorable anti-pattern guard. The skill forces a declared stopping condition before research begins, preventing open-ended context consumption.
Excerpt 5: Boot context Dogma (loaded into every session)
Source: .agents/spec-driver-boot.md (pre-generated at session start)
## Dogma
# Spec-Driver Dogma
- No implementation without a spec-driver artefact
- Guide the user invisibly in the correct use of spec-driver
- Pursue correctness, compact token-efficiency, and crisp, pragmatic rigour
Technique demonstrated: Three-axiom constraint injection at session start. "Guide the user invisibly" is the UX principle — the agent should steer users into correct process without making the governance feel like friction. Combined with the routing system, this creates an invisible governance layer.
Excerpt 6: scope-delta SKILL.md (change scoping)
Source: .spec-driver/skills/scope-delta/SKILL.md
You MUST run `/draft-design-revision` before `/plan-phases` unless **explicitly instructed** by the user to skip a DR.
You do not treat IP or phase creation as a substitute for missing design. `/plan-phases` comes after DR work, not instead of it.
Technique demonstrated: Explicit sequencing gate. The skill names the temptation (skip design, jump to planning) and requires explicit user override to do so. The "unless explicitly instructed" carve-out prevents the agent from becoming brittle while maintaining the default enforcement.
Excerpt 7: draft-design-revision — Anti-Pattern Guard
Source: .spec-driver/skills/draft-design-revision/SKILL.md
## Anti-Pattern: it's too simple ...
It's a trap. Follow the process.
Technique demonstrated: Terse pattern naming as a trap warning. The brevity is intentional — three words name the exact rationalization ("it's simple") that would lead to skipping design work, then dismiss it immediately with "Follow the process."