| name | discovery-mode |
| description | Discovery before implementation — HARD-GATE, YAGNI, incremental. |
Discovery Mode Patterns
HARD-GATE
Do NOT produce any backlog, architecture document, implementation plan, or take any implementation action until you have presented the design or scope and the user has explicitly approved it. This applies to every project regardless of perceived simplicity.
Anti-pattern: "This Is Too Simple To Need Discovery"
Every project goes through this process. A single endpoint, a config change, a utility function — all of them. The simpler the project, the shorter the spec. But the gate must be passed.
One Question at a Time
When clarifying interactively with the user (not generating a client-facing document):
- Ask one question per message
- Prefer multiple-choice over open-ended — it is faster to answer
- If a topic requires multiple questions, break them across separate messages
- Focus each question on: purpose, constraints, or success criteria
- Only one question per message — if more exploration is needed, sequence them
Scope Decomposition Check
Before asking detailed questions, assess the overall scope:
- If the request describes multiple independent subsystems (e.g., "build a platform with chat, billing, file storage, and analytics"), flag this immediately
- Do not spend questions refining details of a project that needs decomposition first
- Help the user split into sub-projects: what are the independent pieces, how do they relate, what order to build them?
- Then run the full discovery flow for the first sub-project only — each sub-project gets its own spec, plan, and implementation cycle
Propose 2-3 Approaches
Before committing to a direction, present alternatives:
- Identify 2-3 meaningfully different approaches with their trade-offs
- Lead with your recommendation and explain why
- Present conversationally — not as an equal-weight menu
- The user can redirect; don't wait for them to ask for alternatives
Applies to: scoping strategies, architectural patterns, technology choices, and any decision with multiple valid paths.
Incremental Validation
When presenting a design, spec, or architecture:
- Present one section at a time
- Ask "Does this look right so far?" before moving to the next section
- Straightforward sections can be 2-3 sentences; complex sections up to 200-300 words
- Revise a section when feedback comes before advancing to the next
YAGNI
Remove unnecessary features from all designs ruthlessly:
- Only include what was explicitly requested or is clearly necessary
- If a feature sounds useful but wasn't asked for, flag it and let the user decide — do not include it silently
- Do not design for hypothetical future requirements
Spec Self-Review
After writing any spec, overview, or architecture document, do a silent inline review before presenting it to the user. Fix issues directly — no need to narrate the review process.
| Category | What to Look For |
|---|
| Placeholders | Any "TBD", "TODO", incomplete sections, vague requirements |
| Consistency | Internal contradictions, conflicting requirements between sections |
| Clarity | Requirements ambiguous enough to cause wrong implementation |
| Scope | Focused enough for a single plan — not covering multiple independent subsystems |
| YAGNI | Unrequested features, over-engineering, future-proofing that wasn't asked for |
Only flag issues that would cause real problems during implementation planning. Minor wording and style preferences are not issues.
Max Iterations
Never run more than 3 clarification rounds without producing a spec or document:
| Round | Purpose |
|---|
| 1 | Initial questions — goals, constraints, success criteria |
| 2 | Clarification of ambiguous answers |
| 3 | Final confirmation of open items |
After Round 3, produce the best possible spec with explicit assumptions noted for every unresolved question. Mark them clearly:
Assumption [A1]: [what was assumed]. Flagged for user confirmation.
Do not ask a 4th round of questions — produce the output and let the user correct the assumptions.
Discovery Lockfile
When multiple agents may run discovery concurrently (e.g., in a parallel spawn), use a lockfile to prevent duplicate discovery sessions from racing:
Run the block below verbatim and in this order. The staleness sweep must come before the bail-out, otherwise a lock left behind by a crashed agent blocks discovery forever.
LOCK=".claude/.discovery-lock"
mkdir -p "$(dirname "$LOCK")"
if [ -n "$(find "$LOCK" -maxdepth 0 -mmin +30 2>/dev/null)" ]; then
echo "Removing stale discovery lock ($(cat "$LOCK"))"
rm -f "$LOCK"
fi
if [ -f "$LOCK" ]; then
echo "Discovery already in progress ($(cat "$LOCK")). Waiting for it to complete."
exit 0
fi
echo "$AGENT_NAME $(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$LOCK"
trap 'rm -f "$LOCK"' EXIT
Rules:
- Write
<agent-name> <ISO-timestamp> to the lock so the owner is identifiable. The timestamp is for humans reading the lock — staleness is judged from the file's own mtime, never by parsing that string.
- Never compute the age with
date -d "$(awk ...)": date -d is GNU-only, so on macOS it fails, and a || echo 0 fallback makes every lock look infinitely old and deletes locks that are still live.
- Remove the lock on EXIT (success or failure) via
trap.
- 30 minutes is the staleness threshold; change it by editing the
-mmin +30 value.
- No scheduled job sweeps orphaned locks. A lock whose owner crashed persists until the next agent runs step 1 above — which is exactly why step 1 must not be skipped or reordered.
- Discovery sessions started by the user directly (not by parallel spawns) do not need the lockfile.
User Review Gate
After the spec self-review passes, always ask the user to review the written document before proceeding:
"Document written to <path>. Please review it and let me know if you want any changes before we move on."
Wait for explicit approval. If changes are requested, apply them and re-run the self-review. Only proceed once the user approves.
