edwinhu/dev-clarify

Announce: "I'm using dev-clarify (Phase 3) to resolve ambiguities."

Iteration topology: one-shot (conversational)

Context Check

Before starting this phase, check remaining context:

| Level | Remaining | Action | |-------|-----------|--------| | Normal | >35% | Proceed | | Warning | 25-35% | Finish the current step, then invoke dev-handoff | | Critical | ≤25% | Invoke dev-handoff immediately — resume fresh |

At Warning/Critical: Read ${CLAUDE_SKILL_DIR}/../../skills/dev-handoff/SKILL.md and follow its instructions.

Contents

• The Iron Law of Clarification
• What Clarify Does
• Process
• Question Categories
• Output

Post-Exploration Clarification

Ask targeted questions based on what exploration revealed. Prerequisite: Exploration phase complete, key files read.

<EXTREMELY-IMPORTANT> ## The Iron Law of Clarification

ASK BEFORE DESIGNING. This is not negotiable.

After exploration, you now know:

• What exists in the codebase
• What patterns are used
• What integrations are needed

Use this knowledge to ask informed questions about:

• Edge cases the code will need to handle
• Integration points with existing systems
• Behavior in ambiguous scenarios

If you catch yourself about to design without resolving ambiguities, STOP. </EXTREMELY-IMPORTANT>

Clarification Facts

• Exploration shows HOW the code works, not WHAT SHOULD happen — patterns found in code are not requirements. When multiple patterns coexist in the codebase, they exist for a reason; which one to follow is a user decision, and picking one by inference is a guess presented as a decision.

No Pause After Completion

After updating .planning/SPEC.md with all clarified requirements, IMMEDIATELY invoke:

Read ${CLAUDE_SKILL_DIR}/../../skills/dev-design/SKILL.md and follow its instructions.

DO NOT:

• Summarize what you learned
• Ask "should I proceed to design?"
• Wait for user confirmation
• Write status updates

The workflow phases are SEQUENTIAL. Complete clarify → immediately start design.

What Clarify Does

| DO | DON'T | |----|-------| | Ask questions based on exploration | Ask vague/generic questions | | Reference specific code patterns found | Repeat questions from brainstorm | | Clarify integration points | Propose approaches (that's design) | | Resolve edge cases | Make assumptions | | Update SPEC.md with answers | Skip to implementation |

Clarify answers: WHAT EXACTLY should happen in specific scenarios Design answers: HOW to build it (next phase)

Process

1. Review Exploration Findings

Before asking questions, review:

• Key files you read
• Patterns discovered
• Architecture insights
• Integration points identified

2. Identify Ambiguities

Common areas needing clarification after exploration:

Integration Points:

• "The existing auth system uses JWT. Should the new feature use the same token or create a new session type?"

Edge Cases:

• "What happens if [condition discovered in code]?"

Scope Boundaries:

• "The existing feature handles X. Should the new feature also handle X or is that out of scope?"

Behavior Choices:

• "I found two patterns in the codebase for this. Pattern A in file.ts:23 and Pattern B in other.ts:45. Which should we follow?"

3. Ask Questions with AskUserQuestion

Smart Discuss (autonomous-chaining requirement): batch ALL open ambiguities into ONE AskUserQuestion call — never ask sequentially across turns. Sequential asks stall autonomous/overnight runs at every question. See Smart-Discuss: Batch Ambiguities below for the batch/don't-batch rule.

Present questions with context from exploration:

AskUserQuestion(questions=[{
  "question": "The auth middleware at src/middleware/auth.ts:78 validates tokens synchronously. The new endpoint needs user data. Should we: validate synchronously (faster, simpler) or fetch fresh user data (slower, always current)?",
  "header": "Auth pattern",
  "options": [
    {"label": "Sync validation (Recommended)", "description": "Faster, uses cached token claims, matches existing patterns"},
    {"label": "Fresh fetch", "description": "Slower, always current, needed if user data changes frequently"}
  ],
  "multiSelect": false
}])

Key principles:

• Reference specific files/lines from exploration
• Lead with recommendation based on codebase patterns
• Explain trade-offs clearly
• One question at a time for complex topics

Smart-Discuss: Batch Ambiguities

When multiple ambiguities are discovered during exploration, batch them into ONE AskUserQuestion call instead of asking sequentially:

Sequential (slow — 5 round-trips):

1. "Should we use REST or GraphQL?" → wait
2. "Should auth be JWT or session?" → wait
3. "Should we support pagination?" → wait ...

Batched (fast — 1 round-trip):

AskUserQuestion(questions=[
  {"question": "API style?", "options": [{"label": "REST"}, {"label": "GraphQL"}]},
  {"question": "Auth mechanism?", "options": [{"label": "JWT"}, {"label": "Session-based"}]},
  {"question": "Pagination?", "options": [{"label": "Yes, cursor-based"}, {"label": "Yes, offset"}, {"label": "Not needed"}]}
], multiSelect=false)

When to batch: After reading exploration findings, if 3+ questions arise, batch them. Present all ambiguities at once with options and pros/cons for each.

When NOT to batch: If a question's answer changes what other questions to ask (dependent questions), ask the blocking question first, then batch the rest.

4. Update SPEC.md

After each answer, update .planning/SPEC.md:

• Add clarified requirements
• Document decisions made
• Note trade-offs accepted

## Clarified Requirements

### Auth Pattern
- Decision: Sync validation
- Rationale: Matches existing patterns, user data changes infrequently
- Reference: src/middleware/auth.ts:78

### Edge Case: Expired Token
- Decision: Return 401, let client refresh
- Rationale: Consistent with other endpoints

Question Categories

Must Ask (based on exploration)

• Integration points with existing systems
• Patterns to follow (when multiple exist)
• Edge cases revealed by code reading
• Testing strategy (if not resolved in brainstorm/explore)

Testing Strategy Clarification (MANDATORY IF MISSING)

<EXTREMELY-IMPORTANT> **If exploration found no test infrastructure, this MUST be resolved now.**

Before proceeding to design, ensure testing strategy is clear:

AskUserQuestion(questions=[{
  "question": "No test infrastructure was found. How should we verify this feature works?",
  "header": "Testing",
  "options": [
    {"label": "Add pytest/jest as Task 0 (Recommended)", "description": "Set up test framework before implementing feature"},
    {"label": "Add E2E tests with Playwright", "description": "Browser automation to test user interactions"},
    {"label": "Add E2E tests with ydotool", "description": "Desktop automation for native apps"},
    {"label": "Other (describe in chat)", "description": "Propose alternative testing approach"}
  ],
  "multiSelect": false
}])

"Manual testing" is NOT an acceptable answer. If user insists on manual testing:

1. Explain: "TDD requires automated tests. Manual testing means we can't do TDD."
2. Ask: "What's blocking automated tests? Let's solve that."
3. If truly impossible: "Then we need to exit /dev workflow and use a different approach."

Do NOT proceed to design without a clear automated testing strategy. </EXTREMELY-IMPORTANT>

Follow-up Testing Questions

After user chooses testing approach, clarify specifics:

AskUserQuestion(questions=[{
  "question": "What's the FIRST test you want to see fail?",
  "header": "First Test",
  "options": [
    {"label": "Happy path - feature works correctly", "description": "Test the main success scenario"},
    {"label": "Error case - feature handles bad input", "description": "Test error handling"},
    {"label": "Edge case - specific boundary condition", "description": "Test a known edge case"},
    {"label": "Integration - feature works with existing code", "description": "Test system integration"}
  ],
  "multiSelect": false
}])

Why this matters: Defining the first test BEFORE implementation is the essence of TDD.

User Workflow Replication (MANDATORY FOR REAL TESTS)

<EXTREMELY-IMPORTANT> **If the test doesn't replicate the user's workflow, it's a FAKE test.**

Based on code path discovery from exploration, clarify the exact workflow:

AskUserQuestion(questions=[{
  "question": "Let me confirm the user workflow the test must replicate:",
  "header": "Workflow",
  "options": [
    {"label": "Confirm workflow", "description": "[State the discovered workflow, e.g., 'highlight → click panel → see status']"},
    {"label": "Modify workflow", "description": "The workflow is different - let me describe it"},
    {"label": "Add steps", "description": "The workflow has additional steps I should know"}
  ],
  "multiSelect": false
}])

Then verify the test approach matches:

AskUserQuestion(questions=[{
  "question": "The test must use [discovered protocol, e.g., WebSocket]. Is this correct?",
  "header": "Protocol",
  "options": [
    {"label": "Yes, use [protocol]", "description": "Test must use the same protocol as production"},
    {"label": "No, different protocol", "description": "Explain the correct protocol"}
  ],
  "multiSelect": false
}])

Verify Test Will Be REAL

After clarifying workflow and protocol, verify:

[ ] Test workflow matches user workflow exactly
[ ] Test uses same protocol as production
[ ] Test interacts with same UI elements user sees
[ ] Test verifies same output user verifies
[ ] Testing skill is appropriate for this workflow

If any of these don't match, the test will be FAKE. Clarify now.

Test Strategy Validation

Before proceeding to design, verify the testing strategy passes real-test enforcement. See references/constraints/real-test-enforcement.md for what constitutes a REAL vs FAKE test.

If the test approach doesn't match what you discovered, STOP and clarify. </EXTREMELY-IMPORTANT>

Optional (if unclear)

• Performance requirements
• Error handling preferences
• Backward compatibility needs

Don't Ask (already decided)

• What the feature does (that's brainstorm)
• Whether to build it (user already decided)
• Architecture approach (that's design)

Output

Clarification complete when:

• All integration points clarified
• Edge cases resolved
• Pattern choices made
• .planning/SPEC.md updated with final requirements
• No remaining ambiguities
• Automated testing strategy confirmed (MANDATORY)

Exit Gate

Checkpoint type: human-verify

Run the canonical 5-step gate before chaining to dev-design — the sub-checks below are its READ/VERIFY content:

1. IDENTIFY: `.planning/SPEC.md` exists and was updated with resolved ambiguities.
2. RUN:      Read(".planning/SPEC.md").
3. READ:     inspect the Testing Strategy + REAL Test Definition sections (the three gate checks below).
4. VERIFY:   every box in all three gate checks is checked; no TBD / placeholder values remain.
5. CLAIM:    only if 1-4 hold, chain to dev-design.

If any sub-check box is unchecked → do NOT proceed; resolve it first.

Testing Strategy Gate Check

Checkpoint type: decision (user chooses testing approach — cannot auto-advance)

Before proceeding to design, verify in SPEC.md:

[ ] Testing approach documented (unit/integration/E2E)
[ ] Test framework specified (pytest/jest/playwright/etc.)
[ ] First test described (what will fail first)
[ ] Test command documented (how to run tests)

If any box is unchecked → STOP. Do not proceed to design.

REAL Test Gate Check (MANDATORY)

Before proceeding to design, verify REAL test criteria:

[ ] User workflow confirmed and documented
[ ] Protocol/transport verified (same as production)
[ ] UI elements to test identified
[ ] Testing skill specified (dev-test-electron/playwright/etc.)
[ ] Test approach matches discovered code paths

If any box is unchecked → You WILL write fake tests. Clarify now.

Fake Test Prevention Gate

See references/constraints/real-test-enforcement.md for detection tables and the Iron Law of REAL Tests.

Ask yourself:

1. Does the test do what the user does? (Not a shortcut)
2. Does the test use the same protocol? (Not a mock)
3. Does the test verify what the user sees? (Not internal state)

If ANY answer is "no" or "not sure" → STOP. Clarify before design.

This is the last checkpoint before implementation planning. Fake tests caught here save hours of wasted implementation.

Phase Complete

Phase summary (append to LEARNINGS.md):

## Phase: Clarify

---
phase: clarify
status: completed
implements: []          # clarification refines requirements; implements no IDs
requires: [SPEC.md, codebase-map]
provides: [clarified-requirements, testing-strategy-validated]
affects: [.planning/SPEC.md]   # may update SPEC.md with resolved ambiguities
questions-resolved:
  - [one-liner per clarification]
---

REQUIRED SUB-SKILL: After completing clarification, IMMEDIATELY invoke:

Read ${CLAUDE_SKILL_DIR}/../../skills/dev-design/SKILL.md and follow its instructions.