Absolute Spec

Start your first response with the 📋 emoji.

Absolute Spec

Absolute Spec turns a fuzzy intent into a reviewed design-spec document — then stops. It is the planning artifact of work, lifted out of the full lifecycle: scan the codebase, ask only the questions the code can't answer, write the spec, run an independent scored review, and hand back a doc you can discuss, hand off, or feed into /absolute work to build.

It is deliberately lightweight. No relentless interview, no task board, no decompose, no execution. One deliverable: a spec good enough that an unfamiliar developer could build from it.

When to use this command

Use spec when:

• You want a design spec to discuss, review, or hand off — not build right now.
• You need to think a feature through on paper before committing to implementation.
• A teammate or another agent will do the building from your spec.
• You want a fast, reviewed design doc without the full phase-gated lifecycle.

Do NOT use spec when:

• You want to design AND build in one flow → use /absolute work (spec is its Phase 2, followed by decompose + safe-wave execution).
• You're documenting code that already exists / already shipped → use /absolute docs (reference/explanation docs, not a forward design).
• The change is a one-line obvious fix needing no design.

The line vs work: spec produces a doc and stops; work produces a doc and then builds it. If you're unsure whether you'll build it now, start with spec — you can chain into work afterward and it will pick the spec up.

Key Principles

1. Codebase before questions. Read what exists first; ask only what code can't answer.
2. Bounded, not relentless. A short clarify pass (3–5 questions), not the depth-first grill work runs. Batching questions is fine.
3. The spec is the deliverable. Quality matters more here than anywhere — keep the independent scored review.
4. Reuse, don't reinvent. Template, scaling rules, and review rubric come from absolute-work's references/spec-writing.md. This command is the thin flow around them.
5. Stop after review. No code, no board, no execution. Hand off cleanly.
6. Never auto-commit. Write the spec file and report; the user commits.

The Flow

SCAN ─→ CLARIFY ─→ WRITE ─→ REVIEW ─→ HANDOFF

No hard gates between steps (that's work). The one checkpoint is the clarify pass — ask, get answers, then proceed straight through to a reviewed spec.

Step 1 — SCAN

Ground the spec in reality before asking anything.

1. Convention detection — read cached config first: if .absolute.config.json or ~/.absolute/config.json exists (from /absolute init), resolve the effective config (project file → global projects["<cwd>"] → global defaults) and use its conventions, detecting only what's missing. No config → soft-suggest init and run work's Codebase Convention Detection table (package manager, language/runtime, test runner, linter, build system, directory conventions; see absolute-work's SKILL.md under Codebase Convention Detection). The spec must speak the project's real stack, scripts, and paths.
2. Deep context scan — read what exists: docs/ (README first), root README.md, CLAUDE.md, CONTRIBUTING.md, docs/plans/ (overlapping/related designs), recent commits (last 10–20), package manifests, and the directories the feature touches.
3. Synthesize — state what you learned in 2–4 lines (stack, relevant existing code, any overlapping prior design). Do not dump a file listing.

Detect the work type (feature / refactor / greenfield / migration) only enough to shape the spec — spec does not run the full per-type question banks.

Step 2 — CLARIFY (bounded pass)

Ask only the questions the codebase genuinely cannot answer — the preference and scope forks. Cap at 3–5 questions; batching is allowed (one AskUserQuestion call with multiple questions where available).

Good questions to ask (when code can't answer them):

• Scope boundary — what's in v1 vs explicitly deferred.
• Behavior forks — real-time vs batch, sync vs async, the genuine "which way" decisions.
• Data/contract shape — only where the design hinges on it and code gives no signal.
• Non-goals — what this explicitly will NOT do.

Do NOT ask: anything a config, manifest, test file, or existing pattern already states. When the code answers it, say so in the spec instead of asking.

If the user said "no questions, just draft it" — skip to WRITE and capture every guess in an ## Open Questions / assumptions section instead.