# Gannonh Kata Kata > Spec Elicitation - Skill: `tomevault-io/gannonh-kata-kata` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/gannonh-kata-kata` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/gannonh-kata-kata/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/gannonh-kata-kata --- # Spec Elicitation Conduct a structured interview to turn intent into a project specification. Drive the conversation through phases, gathering enough detail to produce a spec that a team (human or agent) can execute against. ## Message Format (mandatory) Every message sent during elicitation MUST follow this structure exactly: ``` [1-2 sentence acknowledgment of previous answer, if any] [Single question as a heading or bold text] 1. [Option A] — [brief description] 2. [Option B] — [brief description] 3. [Option C] — [brief description] 4. Something else (describe) **Recommended: [N] ([Option])** — [1-sentence rationale] ``` ### Hard constraints - **One question per message.** Never append a second question, a "related" follow-up, or an "and also." If two things need asking, send two messages. - **Numbered choices on every question** where 3+ reasonable answers exist. Reserve free-form questions for genuinely open-ended exploration (e.g., "Describe your current workflow"). - **Recommendation on every choice set.** State which option to pick and why. The user expects an informed opinion, not a neutral menu. - **No bullet-point sub-questions.** Do not list elaborating questions beneath the main question. Ask them in subsequent turns. ### Violation examples WRONG — two questions in one message: ``` What's the primary use case? 1. Data pipelines 2. One-off conversions 3. Tool integration And who's the main user — yourself, your team, or broader distribution? ``` WRONG — sub-questions under main question: ``` What problem does this solve? For example: - Do you need to convert CSV data for a web app? - Are you processing exports from another system? - Is this for personal automation? ``` WRONG — choices without recommendation: ``` Which approach? 1. CLI tool 2. Library 3. Web service ``` RIGHT: ``` What's the primary use case? 1. Data processing pipelines — automating recurring workflows 2. One-off developer conversions — quick ad-hoc transforms 3. Integration layer — bridging two systems via format conversion 4. Something else **Recommended: 1 (Data processing pipelines)** — most CSV-to-JSON needs recur, making automation the highest-value path. ``` ## Phases Work through these phases in order. Adapt depth to the project. Skip phases that don't apply. Consult `references/guidance.md` for detailed advice on each phase, including when to skip and how to calibrate depth. 1. **Goal** — What problem, who uses it, what does success look like 2. **Constraints** — Stack, platform, timeline, dependencies, prior art 3. **Architecture** — Components, data flow, mermaid diagram (skip for simple scripts or content-only projects) 4. **Acceptance criteria** — Observable, testable, specific conditions 5. **Tasks** (required in output) — 1-3 day chunks, clear boundaries, parallelizable when possible 6. **Non-goals** — Explicit out-of-scope items to prevent scope creep ## Conversation Flow - Acknowledge answers before moving on. Mirror the user's vocabulary. - Handle digressions: answer the side question, then steer back naturally. - Do not loop on the same question if the user redirects. - When a phase is sufficiently covered, move to the next. Do not ask permission to advance unless the answer was ambiguous. ## Completion Gate Before producing the spec: 1. Summarize what was covered and what was intentionally skipped. 2. Ask if anything was missed or needs adjustment. 3. Produce the spec once the user confirms. ## Output Format Structure is flexible. Two requirements: 1. **Tasks section is required.** Use a markdown checklist. 2. **Architecture diagram is strongly encouraged** when the project has multiple components. Use mermaid syntax. Keep the spec concise. Consult `references/guidance.md` for target lengths. ## Saving the Spec After outputting the spec in chat: 1. Write the spec to `plans/spec.md` in the session directory using the Write tool. 2. Call `SubmitPlan` with the path to the written file. `SubmitPlan` presents the spec to the user with an accept/reject UI. When the user accepts, the session transitions from Explore to Execute mode, enabling write operations for implementation. ## Reference Material Consult the `references/` directory for calibration examples and extended guidance: - `guidance.md` — phase depth calibration, acceptance criteria examples, task scoping advice, diagram guidance, spec length targets - `example-feature-spec.md` — sample spec for a feature build - `example-investigation.md` — sample spec for a bug investigation --- > Source: [gannonh/kata](https://github.com/gannonh/kata) — distributed by [TomeVault](https://tomevault.io).