User Spec Planning

User Spec Planning

Thorough adaptive interview → codebase research → completeness review → user-spec.md → three-lane validation → user approval. Output: work/{feature}/user-spec.md with status approved.

Interview Style

Conduct the interview in the language the user writes in. Be an engaged co-thinker: propose solutions, challenge weak answers with concrete examples or code evidence, and keep interviewing until the applicable requirements are understood.

• Ask 3–4 questions per batch and run as many batches as needed.
• Save every question and answer verbatim after each user response.
• Give one substantive challenge to a weak or unclear answer, then accept a supported answer and move to the next gap.
• When the user does not know, offer concrete options or break a required question down. An optional detail may remain an acknowledged limitation; a required detail may not remain TBD.
• Record material choices, rejected alternatives, and reasons in the relevant topic summary so they survive into Accepted Decisions.

When Project Knowledge exists, read its SKILL.md as the router and load only the references relevant to the task. Missing Project Knowledge does not block planning.

Workflow

1. Start or Resume

If the user explicitly asks to continue an existing user spec and provides its feature folder or slug:

1. Use that exact work/{feature} directory. Do not search for other interviews.

2. Read logs/userspec/interview.yml and the existing feature artifacts. Treat any additions or changes in the current request as interview input.

3. Derive the next action from the interview and artifacts:

   • continue with the earliest required topic below 85% or with an unresolved gap;
   • once the general task is understood, create code-research.md if it does not exist, then use it for the remaining questions;
   • when all required topics are complete and no substantive draft exists, run the completeness review;
   • when a filled draft already exists, validate it again with fresh reviewers rather than trying to restore old reviewer responses.

Otherwise start a new spec:

1. Use the current request as the initial task description. If the intended work is not described, ask the user what they want to plan. Infer feature, bug, or refactoring.
2. Choose a kebab-case slug and tell the user which work/{slug} folder will be used. Do not pause only to confirm the slug.
3. If that exact folder already contains prior user-spec work, ask whether to continue that work in the same folder or create the new spec under another slug. If the user chooses the existing folder, follow the resume path above. Never overwrite prior work implicitly.
4. Resolve the directory of this loaded user-spec-planning skill, then from the target project root run its scripts/init-feature-folder.sh with {slug}. Initialize the interview metadata with the start time, last-update time, and in_progress status, then begin the interview.

If at any point the request appears to contain several independently valuable outcomes, explain the proposed split and ask the user whether to separate them. Only after the user agrees, read and apply splitting-user-specs.md. Otherwise do not read that reference and continue the normal workflow.

2. Interview and Research

1. Score the initial description against every interview topic.
2. Complete the general-understanding topics using the interview loop below.
3. Once the intended outcome is clear enough to research, launch code-researcher with the feature path and description. Read code-research.md and use its evidence in later questions.
4. Complete user-flow and integration topics, including applicable failures, edge cases, constraints, deployment, manual user actions, and verification.
5. Make a final pass over every remaining required gap. If a later answer exposes a factual code gap, run focused code research again.

Testing depth follows behavior and risk. Record concrete observable checks and the smallest reliable unit, integration, E2E, build, lint, render, smoke, or manual boundary that can reproduce each applicable risk.

Do not survey hypothetical edge cases. When research or review establishes one concrete rare or unagreed scenario, ask whether the feature should support it before adding requirements. Record the question and answer in conversation_history and update the relevant topic's score, value, and gaps. If accepted, add the behavior to the requirements and acceptance criteria; if declined, record it as an explicit limitation or out-of-scope decision.

3. Check Interview Completeness

Launch a fresh interview-completeness-checker with the feature path and intended scope. It reads the interview, code research, and relevant Project Knowledge and returns the common reviewer JSON directly.

Review findings are diagnoses, not a work queue. Check the evidence and exact response. Apply only an authorized local correction to agreed requirements. For user_decision_required: true, ask one concrete question and record the answer through the existing interview loop before changing artifacts or adding requirements. A false value does not replace this check.

Use supported findings to ask targeted questions for gaps inside the agreed task. Run a fresh checker after the answers are recorded, and draft only after it returns clean.