spec-detailed

/spec-detailed — Create a detailed spec with deeper questioning

Purpose

Produce a more exhaustive, less assumption-heavy specification when the user wants the agent to ask more questions and pin down exactly what should be built.

Use this when precision matters more than speed: product flows, UX details, security-sensitive behavior, migrations, billing, permissions, API contracts, or anything where a wrong default would be expensive.

Invocation

/spec-detailed <description of the work>

Accepted input

A request, problem statement, ticket, mockup, screenshot, user story, or rough idea, with any known constraints and desired level of strictness.

Prerequisites

A HarnessKit workspace (harnesskit init). No approved spec required.

Procedure

1. Read .agent/context/README.md and routing when present. Inspect task-relevant source, existing specs, tests, UI routes, APIs, schemas, and configuration before asking questions. Do not ask for facts available in the repository.
2. Apply requirements-triage and create a discovery map with:
   • confirmed facts;
   • unknowns;
   • assumptions that would affect implementation;
   • preferences that affect UX, API shape, rollout, compatibility, or tests;
   • decision-changing blockers.
3. Ask a structured question batch. Unlike /spec, this command is intentionally more interrogative:
   • normally ask 6–12 focused questions;
   • never ask more than 15 in one batch;
   • group them by product behavior, UX/API/data, edge cases, rollout, and validation;
   • mark each question as blocking, recommended, or optional;
   • provide a proposed default for every recommended or optional question.
4. Wait for the user's answers when any blocking question remains. If the user asks you to proceed with defaults, record those defaults explicitly.
5. Select and announce one planning path:
   • direct-spec for still-small work where detail was needed mainly for clarity;
   • specialist-assisted-spec for cross-cutting work needing one to three specialist planning reviews;
   • full-council-spec for high-risk, irreversible, architectural, security-sensitive, or product-contested work.
6. Use specialist-routing for any relevant planning reviews. Give specialists the same brief and context capsule. Use isolated parallel reports only where the tool supports native subagents; otherwise use clearly labelled sequential or simulated role passes.
7. Produce a complete spec with the normal /spec structure plus these detailed sections:
   • Decision log — each answered question, chosen default, and reason;
   • Alternative behaviors considered — rejected options and why;
   • Acceptance examples — concrete examples or scenarios for critical requirements;
   • Observability and rollout — metrics, logs, flags, migration, rollback when relevant.
8. Save it to .agent/specs/<kebab-case-name>.md using the standard spec frontmatter contract below.
9. Present a concise plain-language decision summary using /sum-spec's output contract. Stop and request approval explicitly. Do not start implementation workers.