requirement-analysis

Language Protocol: Respond in the user's conversation language — an explicit user instruction (including the platform language setting) takes precedence, then the language of the user's recent messages; default to English when neither indicates a language. All deliverables written to the repo (specs, plans, reports, notes) follow the conversation language at creation; incremental edits keep the artifact's existing language. Fixed-wording prompts in this skill are semantic templates — express their meaning in the conversation language, don't quote them verbatim. Language Protocol: output in the conversation language — the user's explicit specification (including platform language setting) takes precedence, then follow the language of the user's recent messages; default to English when neither can be determined. Artifacts written to disk follow the conversation language at creation; incremental modifications keep the artifact's existing language. The fixed wording in this skill is a semantic template; express its meaning in the conversation language rather than copying it verbatim.

Requirements Design Workflow

Through natural collaborative dialogue, turn ideas into a validated, complete design and spec.

First understand the project's current state, then clarify and refine the idea one question at a time; once understanding is sufficient, perform adversarial validation and present a multi-option comparison; after the user approves the design, write the spec to disk, and finally hand off to writing-plans to generate an implementation plan.

Anti-pattern: "This requirement is too simple, no design needed"

All requirements must go through this process. Adding a field, changing a piece of copy, a single-function tool — all the same. "Simple" requirements are precisely where untested assumptions cause the most rework. The design can be very short (a few sentences at the light tier), but itmust be presented and approved。

Checklist

Tasks must be created for each of the following (for Claude Code use TaskCreate, for Codex use update_plan), completed in order; skipped items are marked complete with a reason noted:

Requirements understanding and triage — understand intent, determine the tier, flag external exploration/visual candidates
Parallel exploration — internal code + external resources fan-out in the same wave, depth by tier
Clarifying questions — one question at a time, unlimited rounds; JIT-propose visual-preview for visual questions
Adversarial validation + propose 2-3 options — verify information with sequential-thinking, then give options and a recommendation, user selects
Present the complete design — present the whole thing without splitting into sections, obtain user approval
Write the spec and commit — write to disk .spec-dev/YYYY-MM-DD-NN-<feature>/spec/<feature>-design.md and git commit
Spec self-review + adversarial validation — inline self-check + review subagent; if there are changes, ask the user to review again
Hand off to writing-plans — the sole terminal state; after user confirmation, call writing-plans to generate the implementation plan

Flowchart

digraph requirement_analysis {
    "1 需求理解与分诊" [shape=box];
    "2 并行探索（内部+外部）" [shape=box];
    "3 澄清问题（逐题）" [shape=box];
    "4 对抗验证 + 2-3 方案" [shape=box];
    "用户选定方案?" [shape=diamond];
    "5 展示完整设计" [shape=box];
    "用户批准设计?" [shape=diamond];
    "6 写 spec 并提交" [shape=box];
    "7 self-review + 对抗验证" [shape=box];
    "用户 review 通过?" [shape=diamond];
    "8 调用 writing-plans" [shape=doublecircle];

    "1 需求理解与分诊" -> "2 并行探索（内部+外部）";
    "2 并行探索（内部+外部）" -> "3 澄清问题（逐题）";
    "3 澄清问题（逐题）" -> "4 对抗验证 + 2-3 方案";
    "4 对抗验证 + 2-3 方案" -> "用户选定方案?";
    "用户选定方案?" -> "4 对抗验证 + 2-3 方案" [label="要求调整"];
    "用户选定方案?" -> "5 展示完整设计" [label="选定"];
    "5 展示完整设计" -> "用户批准设计?";
    "用户批准设计?" -> "5 展示完整设计" [label="否，修订"];
    "用户批准设计?" -> "6 写 spec 并提交" [label="是"];
    "6 写 spec 并提交" -> "7 self-review + 对抗验证";
    "7 self-review + 对抗验证" -> "用户 review 通过?";
    "用户 review 通过?" -> "6 写 spec 并提交" [label="要求修改"];
    "用户 review 通过?" -> "8 调用 writing-plans" [label="通过"];
}

The terminal state is calling writing-plans. Must not call executing-plans, acceptance-qa, or any other implementation-type skill — the only skill callable after this skill is writing-plans.

Execution tiers

The tier is determined in Phase 1, declared to the user with the option to override; it only adjusts the scale of exploration and the spec length,and does not exempt any Checklist item or HARD-GATE。

light    — 单文件/单模块、无新依赖、无方案分歧（如加字段、改文案）
           探索：主线程直查或 1 个子代理；方案可收敛为 1 个（说明为何无分歧）；spec 几句话到半页
standard — 默认档。跨 2-3 模块或有方案取舍
           探索：按架构层次或功能模块 3-5 个子代理；完整 2-3 方案对比
deep     — 跨层架构变更、新技术栈、用户使用"彻底/全面/审计"等措辞
           探索：multi-modal sweep，按模态数派发、不设上限；方案对比含更完整的风险分析

Criteria: Number of files and modules involved (preliminary judgment in phase 1, revised in phase 2), whether new dependencies are introduced, whether there are multiple viable solutions to choose from, and the strength of the user's wording. Declaration format: "This requirement is judged as {tier} (reason); if you need something more thorough/lighter-weight, please let me know".

Execution environment compatibility

This skill is compatible with both Claude Code and Codex. Core tool mapping:

Purpose	Claude Code	Codex
User clarification/confirmation	`AskUserQuestion`(single question with options)	Ask a question in a conversation message and wait for a reply
Progress tracking	`TaskCreate` / `TaskUpdate`	`update_plan`
Parallel subtasks	`Agent`(launched all at once in a single response)	`spawn_agent`(inherits context, see codex-compat for parameters) + `wait_agent`
Project specification files	`CLAUDE.md` → `AGENTS.md`	`AGENTS.md` → `CLAUDE.md`
Web search	anysearch skill (embedded) → `WebSearch` fallback	anysearch skill (embedded) → built-in web search fallback (managed `web_search` tool)

For the complete rules of the Codex environment, see codex-compat.md。

Phase 1: Requirement understanding and triage

Goal: Understand the intent and set the parameters for the process.

Understand the core functionality, business entities, constraints, and success criteria; when the description is vague or involves multiple modules, use the sequential-thinking skill (embedded in the plugin) to decompose it
Intent-commitment check: If the user is still in the hesitation period of "whether to do it" (exploratory wording, no delivery commitment) → suggest switching to the exploring skill, and do not force the eight phases; if there are related .spec-dev/explorations/ exploration notes, use them as input for this phase, and do not redo the already-explored parts in phase 2
Small-fix check: If the requirement is actually a small bug fix/small adjustment that has already been decided and has no design space (single-point bug, single constant, single copy text, no solution trade-offs, does not span modules, does not introduce new dependencies) → suggest switching to the quick-fix skill, and do not force the eight phases; this is the dual of the intent-commitment check—that one blocks "haven't decided whether to do it yet", while this one blocks "decided, but not worth going through full design". It is a suggestion (no automatic switching), and the user decides. For committed development requests whose size/design space is uncertain, also suggest going through quick-fix first—its step 2.5 escalation gate based on root-cause evidence (including context handoff) is more accurate than guessing at the entrance; escalating is cheap, while downgrading is wasteful
Task-type check (authoritative definition of the report channel): If the requirement has a committed delivery, but the deliverable is not a code change (non-development deliverables such as research reports, solution comparisons, log analyses, etc.) → suggest using the report channel, and do not force the eight phases: do not create a feature directory, do not write spec/plan; when needed, clarify the focus points according to the clarifying discipline; after the main thread produces conclusions,ask once"Persist to disk as .spec-dev/reports/YYYY-MM-DD-NN-<topic>.md ?" (lightweight structure: question, conclusion, source of evidence; the directory is created with the first report; the same NN sequence is shared by all .spec-dev/ date-prefixed artifacts), and if the user declines, keep only the conversation and persist nothing. It is a suggestion, and the user decides. When the conclusions need to be turned into code, return to normal triage—the report channel is not a backdoor for implementation
Scope decomposition check: The intent of the requirement must be expressible in one sentence—if it can't be stated clearly, it should be split. When a too-large signal appears (the scope reads like a list of unrelated features, reviewing one spec takes an entire afternoon, two people working on it simultaneously would collide, half the tasks can be delivered independently) or multiple independent subsystems are described (e.g. "build a platform with chat, file storage, billing, and analytics"), point this out immediately and first help the user decompose it into sub-projects (each with its own independent spec → plan → implementation cycle)—do not waste clarification rounds on a project that needs decomposition. Stating the decomposition is not the end of it; two accompanying actions:
- Decomposition registration (roadmap): After the user confirms the split plan (sub-project list, one-sentence scope, dependency order), persist it to disk per roadmap-template.md as .spec-dev/roadmaps/YYYY-MM-DD-NN-<project>.md(products sharing the same NN sequence all use the .spec-dev/ date prefix) and git commit (at registration time, simultaneously fill in the "Original Requirement" section—the user's full original words—and each sub-project's "Context Capsule"—key decisions/exploration pointers/scanned scope), then run this process only for the first (or user-specified) sub-project. The roadmap is the only persistent location for decomposition decisions—if it isn't written to disk, the remaining sub-projects live only in this conversation and silently evaporate once the session ends
- Continuation check: When the requirement matches an existing sub-project of some active roadmap (the user names "continue <project>", or a pending sub-project of some active roadmap under .spec-dev/roadmaps/ matches this requirement) → load that roadmap's goals/decomposition boundaries/notes,and read the preceding artifacts pointed to by that sub-project's context capsule(the "Background and Goals" and acceptance report conclusions of the preceding sub-project's spec, and exploration pointer files), use these as stage 1-2 input to run this process directly, without re-decomposing,and without requiring the user to provide the original requirement again; for stage 2 exploration, do not re-scan modalities already registered in the capsule's "scanned scope"—only fill the gaps; if a depended-upon preceding sub-project has not been delivered, point this out to the user first. If the roadmap directory does not exist or there is no match → this clause entails zero action, and the process proceeds normally
Determine the tier and declare it (see "Execution Tiers")
Set markers for consumption by later stages:
- External exploration needed?—involves a new third-party library/framework, requires the latest industry practices, or has insufficient internal examples; if any of these holds, mark it
- Visual candidate?—mark it when the requirement involves topics that are "clearer to see than to say", such as UI layout, page structure, visual style; this marker only affects the JIT proposal timing in stage 3,and is not proposed at this point
- Contract posture determination: When the requirement wording contains a destructive refactoring signal ("refactor", "overturn", "may break", "no compatibility needed", etc.) and is expected to touch existing active specs/ADRs,confirm it on the spot in this stage (before stage 2 dispatch) with a single clarification question:are these old contractshard constraints(default) ormerely current-state input—the posture conclusion determines the exploration dispatch wording and cannot wait until stage 3. After downgrading is confirmed: both the stage 2 main-wave and backfill exploration dispatch wordings must carry this posture conclusion, and sub-agents must not report the downgraded contract as a design constraint (it serves only as input for current-state and migration analysis); stage 4 solution comparison must not exclude options for "violating the old spec contract"

Stage 2: Parallel Exploration

Goal: Gather internal code facts and external best practices in one wave.

Primary task: Find and read the project specification files (priority per the environment mapping table).

Orchestration: Internal and external exploration are independent of each other,all subagents must be launched at once in a single message—launching in batches degrades into serial waiting. There is no upper limit on the number of subagents; it is determined by the tier and the structure of the requirements:

light: Direct lookup by the main thread (Glob/Grep/Read or codegraph), or 1 code-explorer
standard: Split into 3-5 by architectural layer or functional module code-explorer; when phase 1 marks external exploration, add 1-2 in the same wave external-resource-explorer
deep: multi-modal sweep—one per modality code-explorer blind-scanning each other, the number of modalities is determined by the project's form with no upper limit; externally split into multiple by topic external-resource-explorer launched in the same wave

External exploration tool priority: AnySearch (general/vertical/batch, embedded in the plugin) first → WebSearch / WebFetch as fallback;when dispatching external exploration subagents, this priority must be proactively restated in the dispatch prompt(do not rely on the agent definition file taking effect, especially on the Codex side); for the degradation chain and modality definitions, contract validation, and failure isolation rules, see exploration-patterns.md。

Each subagent must be given: a clear topic or modality, relevant file clues, expected output format, tool priority, and a reminder of document timeliness rules (the latter two are defined in the exploration-patterns dispatch requirements). A failed subagent first retries once with a narrowed scope, and if it fails again the main thread takes over.

Phase 3: Clarifying questions

Goal: Resolve all vagueness, ambiguity, and trade-offs among multiple solutions.

Questioning discipline follows the core discipline of the clarifying skill (a referenced pattern; the discipline definition is governed by clarifying): Self-disclosure before asking (the three sections of assumptions/key information/easy-to-err come first), ask only one question at a time, prefer multiple choice with the recommended option first (Claude Code uses AskUserQuestion), leave fact self-check decisions to the user, order by decision dependency, challenge terminology, do not fabricate questions—if there is no doubt, explicitly record "requirements are clear, no clarification needed" and proceed to phase 4. This phase is a referencing party: after clarification is complete, proceed directly to phase 4 without triggering clarifying's consensus summary and three exits. For the Codex per-question questioning specification, see the Codex specification section embedded in clarifying; for the dialogue presentation requirements of the three gates, see codex-compat.md。

Prioritize coverage: purpose, constraints, success criteria; the ambiguities, constraint conflicts, implicit assumptions, and edge cases exposed in phases 1-2
The canonical terminology adjudicated by terminology challenges is used throughout, and the canonical name, one-sentence definition, and Avoid aliases are recorded in the spec glossary (the challenge action belongs to the clarifying discipline; writing the glossary to disk is the responsibility of this phase)

Visual preview (JIT proposal): Do not propose at the opening. When some questionis clearer seen than said(a genuine mockup/layout/diagram question, not merely "the topic involves UI"), at the moment it first appears, send a separate message proposing the use of the visual-preview skill—that message contains only the proposal and carries no other questions. If the user accepts, execute per the visual-preview skill; if rejected, continue with plain text and do not propose again. Judge browser vs. terminal per question: if the content itself is visual (wireframes, layout comparisons, architecture diagrams) use the browser; if the content is textual (requirements, trade-offs, concept choices) stay in the terminal.

Backfill exploration: If a new library/new domain is discovered during clarification or the solution phase, one round of external exploration may be backfilled (also initiated by a single response); after backfilling, continue with the current phase.

Phase 4: Adversarial verification + propose 2-3 solutions

Goal: First falsify your own information, then give comparable solutions.

Zero sub-agents: This phase is completed entirely on the main thread, using the sequential-thinking skill (embedded in the plugin, bun/tsx → automatically falls back to the scripts/think.mjs Node port) to advance in a structured way; when neither the skill nor its runtime is available, fall back to explicitly reasoning through points in the reply and note the reason for tool degradation—do not skip the analysis due to missing tools.

Step 1—Adversarial verification of information. Interrogate each load-bearing conclusion collected in phases 1-3 (facts that will directly determine the choice of solution), one by one:

Is the source reliable? (External conclusions: official documentation or secondhand blog? Version timeliness?)
Does it conflict with codebase facts? (When external best practices contradict the project's existing patterns, reread the code to adjudicate)
Is it an unverified assumption? (If yes → flag it; if it can be verified in the code, verify it immediately; if only the user can adjudicate it, go back to phase 3 to ask a follow-up question)

Do not enter solution design before the conflict is resolved.

Step 2—Propose 2-3 solutions. Based on the verified information, provide a solution comparison:

For each solution: core approach, fit with existing patterns, change radius, risk, cost, and degree of compliance with design principles (compare against the eight items in writing-plans/references/design-principles.md—especially the three questions "does it introduce speculative abstraction," "does it leave a compatibility shim," and "is it a stopgap")
Put the recommended solution first and explain the reason, present it conversationally, and do not pile up tables
YAGNI: Remove features nobody asked for from all solutions
For the light tier, when there is truly no disagreement, this can converge to 1 solution, but you must explain "why there is no disagreement"
Only after the user selects a solution do you enter phase 5; if the user proposes adjustments, revise the solution and present it again

Phase 5: Present the full design

Goal: Expand the selected solution into a complete design and obtain approval for the whole document.

Present the whole document and do not confirm section by section—give the full text at once, and let the user give overall feedback
Cover: architecture and component division, data flow, key interfaces/data structures, error handling, testing strategy, risks and edge cases
Length matches complexity: a few sentences for the light tier, and at most two to three hundred words per section for complex designs—a design document is not better the longer it is
Aim for isolation and clear design: Split into units with a single responsibility, clear interfaces, and independent comprehensibility and testability; each unit can answer "what it does, how to use it, what it depends on"; one can understand a unit without reading its internal implementation, and changing the internal implementation does not break consumers—if this cannot be achieved, redraw the boundaries; self-check the overall design against the eight items in design-principles.md
In an existing codebase: Follow existing patterns; existing problems touched by the current work (oversized files, messy boundaries) may be included in the design for targeted improvement, but do not do unrelated refactoring
Do not enter phase 6 before the user approves; if there are revision comments, revise and present the whole document again

Phase 6: Write the spec and submit

Create a feature directory for this requirement .spec-dev/YYYY-MM-DD-NN-<feature>/(all spec-dev artifacts are uniformly collected in the project root directory .spec-dev/ down; NN is the two-digit sequence number for the day — scan .spec-dev/ down the existing date-prefixed artifacts for the day (the feature directory, and the filenames under reports/、roadmaps/ ) take the maximum plus one, starting at 01,rescan once before writing to disk to prevent concurrent number collisions: if the same number is found to be taken, move to the next number and synchronously fix self-referencing paths; for feature, take a short semantic name from the requirement topic, following the project language; existing old naming YYYY-MM-DD-<feature> directories are not renamed (grandfather); the same NN sequence is shared by all .spec-dev/ date-prefixed artifacts), and write the approved design into its spec/<feature>-design.md(the user's preference for the spec location takes precedence over this default)
The spec and the later writing-plans plan (same directory plan/ split-file form: index.md + tasks/ + progress.yaml) share this one feature directory — all artifacts of one requirement are kept in one place
Decision triage (ADR): check whether among the "confirmed key decisions" there is a decision that simultaneously satisfies all three criteria —hard to reverse(high cost to change one's mind afterward),confusing without context(future readers will ask "why was it done this way back then"),real trade-off(a genuine alternative existed and one was chosen for a specific reason) — each qualifying decision is recorded as a repository-level .spec-dev/adr/NNNN-<slug>.md(the whole project shares one directory and a unified numbering: scan the existing highest number and increment; if the directory does not exist, create it with the first ADR;rescan the directory once before writing to disk to prevent number collisions— a parallel session may already have used the same number; if a file with the same number is found to exist, move to the next number and synchronously fix the self-referencing number in the body and links; the body only needs 1-3 sentences stating the background, decision, and rationale, with a one-line note for rejected options worth remembering), the spec decision section keeps a one-line summary and links over; if any of the three criteria is missing, do not create an ADR — ADR proliferation is as useless as having no ADRs.ADR status discipline: each ADR has a status line under its title, with a closed set of three states —**Status**: Accepted (YYYY-MM-DD) / **Status**: Deprecated (YYYY-MM-DD) — <一句原因，强制> / **Status**: Superseded by [ADR-NNNN](NNNN-<slug>.md) (YYYY-MM-DD)(relative links to filenames in the same directory, numbering mandatory; historical ADRs missing a status line are treated as Accepted). One-sentence criterion: if there is a replacement decision, use Superseded; if there is no replacement and the decision context has disappeared, use Deprecated. After Accepted, the body is immutable (only the status line, typos, and broken links may be changed);no partial overturning— when overturning any part of an existing ADR, the new ADR fully restates the conclusions that remain valid and replaces it as a whole, declares the **Supersedes**: ADR-NNNN line under the title, and in the same commit at this stage writes back the old ADR's status line as Superseded by (ADR supersession takes effect immediately with the ruling, without waiting for implementation delivery)
Supersede triage: for each active spec whose behavior intersects with what phase 2 exploration finds, make a three-way classification judgment and write it into the spec —complete supersession(the new spec wholly replaces the old feature) andpartial supersession(replacing part of the old spec's Requirements) are registered in frontmatter supersedes(paths relative to the repository root) and in the body section "Supersession and Coexistence" (partial supersession must list the specific Requirement titles being superseded, each with a one-sentence reason for supersession);faceted coexistence(different behavioral facets of the same file, no conflict) is not registered in supersedes; record one line of rationale for the judgment and each declares covers. For the section template and annotation format, see spec-template.mdWhen the user requests deletion of an entire feature and no new behavior takes over, produce a lightweight spec containing only REMOVED Requirements as the successor (record the deletion rationale; on delivery, write back to the old spec as a full replacement). The spec's replacement write-back takes effect upon delivery (the final task of executing-plans), forming a dual track with the ADR's immediate write-back.
Structural reference spec-template.md, add or remove sections as needed;behavioral requirements must be expressed using the Requirement + Scenario structure（### Requirement: one SHALL per requirement and observable,#### Scenario: use GIVEN/WHEN/THEN—they are the direct anchors for subsequent TDD tests and acceptance); when modifying existing functionality, the behavior section switches to the three-section delta (ADDED/MODIFIED/REMOVED Requirements, see template)
Drift guard anchor (required): when writing to disk, retain the spec_dev frontmatter at the top of the template, fill in feature and covers(the code path glob owned by this feature; for pure documentation features leave an empty array []) — at this stage status stays draft. This frontmatter is the anchor for the pre-commit / CI drift guard; missing it or leaving it forever in draft means this feature's code is not protected by the "code changed but spec not synced" interception
roadmap backfill (only when this feature is a sub-item of an active roadmap): backfill the feature directory path into the corresponding sub-item row of the roadmap, set status to in-progress; if it does not belong to any roadmap, skip this step
git commit the spec file, the newly added ADR file, and the roadmap backfill (only these files; if it is not a git repository, skip and explain to the user)

Phase 7: Spec self-review + adversarial verification

Step one—inline self-check(reread with fresh eyes yourself, fix on discovery, no re-review needed):

Placeholder scan: are there any "TBD", "TODO", unfinished sections, or vague requirements?
Internal consistency: do the sections contradict each other? Does the architecture match the functional description? Are terms used consistently throughout with the canonical names from the glossary, without mixing in Avoid aliases?
Scope check: can the intent of the entire spec be stated in one sentence? Is it focused enough to be carried by a single implementation plan? If oversized signals appear (a list of unrelated features, half the tasks deliverable independently), go back to decomposition.Beware of pseudo-focus: the spec body itself writes phased structures like "first stage/Phase 1, second stage/Phase 2..." or "do X first then Y"—this is unregistered decomposition disguised as a focused spec (it reads as focused but actually stuffs multiple implementation cycles into one spec; downstream writing-plans will only write a plan for the first stage, and the remaining stages silently evaporate). If hit, go back to the Phase 1 scope decomposition check: split the stages into roadmap sub-items, and keep only the first stage's content in this spec
Ambiguity check: are there requirements that can be interpreted in two ways? If so, choose one and state it explicitly
Requirement quality: does each Requirement have exactly one SHALL and is it observable? Does each have at least one Scenario that truly tests it (not a restatement)? Do the scenarios most feared to break have named Scenarios? For the three-section delta (if used), does the classification match the existing behavior?

Step two—adversarial verification: dispatch 1 temporary subagent (use general-purpose for Claude Code, use spawn_agentfor Codex), with the prompt following spec-reviewer-prompt.md Template construction, performing an independent review of the spec (completeness/consistency/clarity/scope/YAGNI). Handle each issue reported by the review one by one: if valid, fix the spec; if not, record the reason.

Step 3 — user review gate：

"The spec has been written and committed to <路径>. Please review it; if changes are needed, let me know, and once confirmed we will begin writing the implementation plan."

Wait for the user's reply.If the spec was modified in Step 1 or Step 2, the user must be made to re-review the modified version; if the user requests changes, make them and rerun this phase. Only after the user confirms do we proceed to Phase 8.

Phase 8: Handoff to writing-plans

Precondition confirmation: Must have the user's explicit consent to "begin writing the implementation plan" — the confirmation wording in Phase 7 already includes this question; if the user only approves the spec and has not indicated whether to continue, first ask "Shall we begin writing the implementation plan now?", and only hand off after they agree
Activate the drift guard: Before handoff, flip the spec frontmatter's status: draft to active and commit (only active participates in drift interception — if not flipped, the guard is silently disabled for this feature)
Post a supersession notice (only when the spec's supersedes is non-empty): In the same commit that flips active, write a Superseded-pending annotation under the H1 title of each old spec pointed to (for the format see the "Supersession annotation format" section of spec-template; for partial supersession, state the title of the Requirement to be superseded) — thereby making the dual-active state during the window explicitly determinable by all consumers; if this plan is later abandoned, the annotation is reclaimed by executing-plans' intent-level deviation wrap-up
Invoke the writing-plans skill to generate an implementation plan based on the approved spec
Do not invoke any other skill— writing-plans is the only next step in this flow; implementation discipline (worktree isolation, TDD, review orchestration) is carried on by the writing-plans → executing-plans chain

Key Principles

One question at a time— do not overwhelm the user with a string of questions
Multiple-choice questions preferred— if concrete options can be given, do not ask open-ended questions
Ruthless YAGNI trimming— remove unnecessary features from all designs
Falsify before proposing— load-bearing information must not enter solution design without adversarial verification
Compare multiple options— before finalizing, always produce 2-3 options (the light tier is an exception and requires justification)
Incremental verification— pass the three gates one by one: option selection, design approval, and spec review
Roll back at any time— if a misunderstanding is found, return to the corresponding phase to clarify, and do not proceed with erroneous assumptions
Principles before preferences— option comparison and design finalization use design-principles.md as the common adjudication dimension

Red Flags

When the following thoughts arise, stop and re-check against the Checklist:

"This is too simple, let's just write the code" → The HARD-GATE applies to all requirements
"Asking several questions at once is more efficient" → One at a time
"Just use the approach found from external search directly" → Verify adversarially first, against the codebase facts
"The option is obvious, no need to compare" → Unless it is the light tier with justification, produce 2-3 options
"Once the design is approved, the spec doesn't need to be shown to the user again" → after self-review, any changes must be reviewed by the user again
"Write the code along the way" → the terminal state is only writing-plans; implementation is the responsibility of a subsequent skill
"Start work first, fill in the tier/task checklist later" → create a task for each checklist item; if skipping, note the reason
"The project is too big, do the first part first and deal with the rest later" → decomposition must be written to disk as a roadmap: "later" is equivalent to nonexistent if it isn't registered
"Splitting the spec into phases (Phase 1/2/3) is enough to accommodate a large goal" → a phased spec is an unregistered decomposition; split it into roadmap subprojects and keep only the first one in the spec