User Spec Planning

Thorough adaptive interview → codebase scan → user-spec.md → dual validation → user approval. Output: engagement/specs/user-spec.md with status approved.

Who runs this. SDD phase 1 of a dev engagement (see dev-methodology §"Spec-Driven Development"). agency-intake runs it in the main loop, step 5c, because the interview needs the user and nobody inside engagement-workflow can reach the user. It is never a specialist task inside the engine. Paths below are relative to the project root that holds engagement/.

engagement/specs/ is the feature folder. Every agent that takes a feature_path input (code-researcher, interview-completeness-checker, both userspec validators, and later the tech-spec validators) gets feature_path = engagement/specs; their default sub-paths (code-research.md, logs/userspec/…) then land inside specs/, which the whitelist allows.

Interview Style

Conduct interview in Russian. Be thorough and opinionated — an engaged co-thinker who actively proposes solutions and challenges weak answers.

How to interview:

• 3-4 questions per batch. Run as many batches as needed until the cycle's items are fully covered.
• Propose solutions based on Project Knowledge: "В architecture.md описан паттерн X — думаю, здесь нужно Y. Согласен?"
• Challenge with substance — concrete counterexamples, code references, unexplored scenarios: "А что если пользователь сделает Z? В коде модуль Q не обрабатывает этот случай."
• Accept the answer after one substantive challenge and move on to the next gap.
• When user says "не знаю": help think through it (examples, common patterns). Optional item → mark TBD. Required item → break into simpler questions.

Interview depth depends on feature size (S/M/L in interview metadata):

• S (1-3 files, local fix): focused interview, core behavior
• M (several components): moderate depth, integration questions
• L (new architecture): deep interview, thorough edge cases and risk analysis

Process

Phase 0: Init

1. Check for existing interview: engagement/specs/logs/userspec/interview.yml with metadata.status: in_progress. If found — load, show discussed topics summary, resume.
2. Check for existing feature research: look for engagement/specs/research-verdict.md. If found and verdict is GO or CONDITIONAL:
   • Read verdict, use findings as starting context for interview
   • Skip code scanning in Phase 3 if code-research.md already exists from feature-research
   • If CONDITIONAL: bring up conditions during interview, confirm they are addressed If not found: proceed normally (feature-research is recommended for M/L features but not required).
3. Get task description: "Опиши, что хочешь сделать."
4. Determine work_type (feature / bug / refactoring) from description.
5. Propose feature name (kebab-case), get user confirmation. It becomes the engagement name; the two SDD engagements are {name}-spec and {name}-impl.
6. Create the state: mkdir -p engagement/specs/logs/userspec && cp ~/.claude/shared/interview-templates/feature.yml engagement/specs/logs/userspec/interview.yml. Do not run init-feature-folder.sh: it builds the retired work/{feature}/ layout.
7. Update interview.yml: set metadata.started, metadata.status: in_progress, phase1_feature_overview.feature_name, phase1_feature_overview.work_type.

Checkpoint: interview.yml exists with status in_progress, feature name confirmed.

Phase 1: Study Project Knowledge

Read ALL files from .claude/skills/project-knowledge/references/. If the directory is missing, empty or still holds template placeholders, this is a new project: stop and return to agency-intake step 5c.0 (bootstrap) before any feature interview.

These files are your context for the entire interview. Reference them when asking questions and proposing solutions.

Phase 2: Cycle 1 — General Understanding

Scope: phase1_feature_overview items in interview.yml.

1. Score user's initial description against all items (detailed 80-95%, brief 50-70%, vague 20-40%, not mentioned 0%).
2. Run interview loop (see below) on phase1_feature_overview items.
3. During this cycle — determine feature size S/M/L and agree on testing strategy:
   • S: integration/E2E usually not needed — state why
   • M: propose whether integration tests make sense, explain reasoning
   • L: propose specific integration and E2E scope with justification

Phase 3: Code Scanning

Launch code-researcher subagent (Task tool, opus) with feature_path = engagement/specs and the feature description from Cycle 1.

After subagent completes — read engagement/specs/code-research.md. Use findings in Cycle 2 questions. The same file travels into both SDD engagements; the tech architect deepens it later.

If during later phases a gap is discovered — launch code-researcher again with the specific question to investigate.

Phase 4: Cycle 2 — Code-Informed Refinement

Scope: phase2_user_experience + phase3_integration items.

1. Summarize understanding: "Я понял задачу так: [X]. Делать планирую так: [Y, based on code]."
2. Questions based on code findings: "Нашёл модуль X, который делает Y — переиспользуем?"
3. Cover deploy and user actions (items deploy_approach, manual_user_actions):
   • "Нужны ли ручные шаги для запуска? (создать бота, получить API ключи, настроить сервис, зарегистрироваться где-то)"
   • "Как деплоить? Что нужно настроить? (уже есть CI/CD, нужно настроить, ручной деплой)"
   • "Как проверить что работает после деплоя? (MCP-инструменты, curl, ручная проверка)"
   • "Что можно проверить прямо во время разработки, без деплоя? (вызвать внешний API, запустить локально, проверить конфиг, потыкать UI на localhost, протестировать промпт)"
4. Run interview loop on phase2 + phase3 items.

Phase 5: Cycle 3 — Review & Finalize

Scope: ALL items across all phases still below threshold.

Cleanup pass: revisit anything not fully covered in Cycles 1-2. Deepen edge cases and error scenarios — probe for scenarios user hasn't considered, even if items formally passed threshold.

Run interview loop on remaining gaps.

Phase 6: Completeness Check

Launch interview-completeness-checker subagent (Task tool, sonnet) with feature_path = engagement/specs. It reviews interview.yml against PK files and code-research.md.

• needs_more → ask the suggested questions, re-run checker
• complete → proceed to Phase 7

Phase 7: Create User Spec

1. Copy template to working file:
   • Copy ~/.claude/shared/work-templates/user-spec.md.template → engagement/specs/user-spec.md
   • Edit sections one by one using Edit tool, replacing placeholders with interview data Reason: agent sees template structure and comments while editing each section, preventing drift from template format.
2. Content rules:
   • "Что делаем" — self-contained, understandable without the interview
   • "Зачем" — concrete user value, not "улучшить UX"
   • Acceptance criteria — testable, no "работает корректно"
   • Every acceptance criterion gets a stable id AC-1, AC-2, … (- [ ] AC-1: …). The tech-spec traces its tasks to these ids and the impl engagement's criteria.md cites them, so an id is never renumbered or reused once the spec is approved.
   • Every discussed topic from interview must appear in the spec
3. If feature seems large (>10 criteria, >3 user flows, >5 integrations) — suggest splitting.

Phase 8: Validation

Run 2 validators in parallel (Task tool) with feature_path = engagement/specs. Their reports land in engagement/specs/logs/userspec/, NOT in validation-outputs/: that directory belongs to the engine's validate phase and the precheck parses every JSON in it.

• userspec-quality-validator (sonnet) — document structure, template compliance, formal completeness. Returns JSON with per-check pass/fail and findings list.
• userspec-adequacy-validator (opus) — feasibility, over/underengineering, better alternatives. Returns JSON with findings by category and severity.

Handling findings:

• Obvious issue → fix silently
• Borderline → discuss with user
• Disagree with finding → reject with reasoning
• Conflict between validators → userspec-adequacy-validator takes priority (substance over form)

After each validation round (validators wrote reports + you applied fixes), re-run validators. Max 3 iterations, then show remaining issues to user.

Phase 9: User Approval

Show user-spec.md link + validation summary. If changes requested — edit and show again.

When approved:

1. Set user-spec.md frontmatter status: approved and approved: {YYYY-MM-DD}
2. Set interview.yml metadata.status: completed
3. Return to agency-intake step 5c: it writes the {name}-spec engagement's criteria.md.

After approval the user-spec is frozen. Only the user changes it: a gap found later (by the architect, a validator or the manager) comes back to the user as a question, and the fix is a re-approval, never a silent edit.

Interview Loop

Runs inside each cycle. Repeats until the cycle's scope is fully covered.

1. Find gaps: required items in current scope with score < 85%. Lowest first.
2. Ask 3-4 questions about different gaps. Reference PK and code findings.
3. User responds.
4. Update interview.yml:
   - conversation_history: add full Q&A entry
   - Item: score, value, gaps, status
   - metadata: last_updated, current_question_num
   - Save immediately
5. Check stop criteria (BOTH must be true):
   a) All required items in scope score >= 85%
   b) Structural: every required item has non-empty value,
      no TBD in value, gaps empty or only conscious limitations
6. Not done → step 1. Done → exit cycle.

Scoring: detailed answer 80-95%, brief 50-70%, vague 20-40%, not mentioned 0%.

Optional items: cover when user mentions relevant context or when naturally connected to required items.

Work Type Adaptations

All three cycles apply to any work_type, but focus shifts:

Bug: Cycle 1 → reproduction steps, expected vs actual, severity, when it broke. Code scanning → find bug location and root cause. Cycle 2 → fix approach, regression risks.

Refactoring: Cycle 1 → current problems, target architecture, stability guarantees. Code scanning → current structure, dependencies, test coverage. Cycle 2 → migration path, backward compatibility.

Scope Changes

If understanding changes significantly during interview:

• Update affected scores downward, add new gaps
• Reassess feature size (S/M/L)
• If work_type changes (was feature, actually bug) — pivot items accordingly
• Note the change in interview.yml notes section

Self-Verification

• All cycles completed, completeness checker passed
• user-spec.md filled with real content (no placeholders), every AC has an AC-N id
• Both validators passed (or issues resolved with user)
• User approved, frontmatter status: approved
• interview.yml metadata.status: completed
• Control returned to agency-intake step 5c