[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72TKRENHARTCC8CPC833ENB":3,"skill-same:01M72TKRENHARTCC8CPC833ENB":95},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M72TKRENHARTCC8CPC833ENB","ywc-plan",null,"(ywc) Use when a rough feature idea or change request needs a concrete plan, scale assessment, and routing before implementation. Triggers: \"plan 세워줘\", \"계획 세워\", \"plan this\", \"make a plan\", \"プラン作成\", \"計画立てて\", \"ywc-plan\". Do not use for spec validation (use ywc-spec-validate), finalized-spec task decomposition (use ywc-task-generator), product\u002Fbusiness reasoning (use ywc-product-review), or architecture-only exploration (use ywc-tech-research).","yongwoon\u002Fywc-agent-toolkit","yongwoon","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F9317029?v=4","01M72SZSF6VKANKG5QTMV4V95S","01M72SZSG8HHC3W2CV5P7EJ5AH",8,"MIT","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002FSKILL.md",[],[],"2026-11-10 22:39:42",false,"---\nname: ywc-plan\ndescription: >-\n  (ywc) Use when a rough feature idea or change request needs a concrete plan,\n  scale assessment, and routing before implementation. Triggers: \"plan 세워줘\",\n  \"계획 세워\", \"plan this\", \"make a plan\", \"プラン作成\", \"計画立てて\",\n  \"ywc-plan\". Do not use for spec validation (use ywc-spec-validate),\n  finalized-spec task decomposition (use ywc-task-generator), product\u002Fbusiness\n  reasoning (use ywc-product-review), or architecture-only exploration (use\n  ywc-tech-research).\n---\n\n# ywc-plan\n\n**Announce at start:** \"I'm using the ywc-plan skill to clarify the request, assess scale, and route to the appropriate downstream path.\"\n\nThis skill converts a rough idea, vague request, or partially-formed change description into one of two artifacts: (1) a **direct execution plan** for Small changes that can be implemented in a single PR without task decomposition, or (2) a **spec document** for Medium\u002FLarge changes that will be handed off to `ywc-spec-validate` and then `ywc-task-generator`. Input: natural-language request from the user. Output: either a `plan.md` (Small path) or a `docs\u002Fywc-plans\u002F\u003Cfeature>.md` (Medium\u002FLarge path), plus an explicit handoff instruction.\n\n## Arguments\n\n| Flag | Type | Description |\n|---|---|---|\n| `--non-interactive` | flag | Skip interactive clarification prompts in Step 1. If any anchor is missing, fill with defaults: Out of Scope = `\"nothing explicitly excluded\"`, Done When = `\"all tasks merged and ywc-impl-review returns DONE\"`. Also suppress automatic `ywc-spec-ready`; print the manual handoff instead. |\n| `--no-converge` | flag | Suppress automatic `ywc-spec-ready` for a fresh Medium\u002FLarge spec and print the manual handoff instead. Small and Re-plan paths do not run automatic readiness regardless. |\n| `--update-spec \u003Cpath>` | string | Path to an existing spec file. Activates Re-plan Mode (Step 4c). Must be used with `--failure-context`. Mutually exclusive with normal spec generation. |\n| `--failure-context \u003Ctext>` | string | The \"Fix Priority\" section text from `ywc-impl-review`. Used together with `--update-spec` to identify which parts of the spec need amendment. |\n| `--output \u003Cpath>` | string | Explicit output path for the generated spec or plan (e.g., `--output docs\u002Fywc-plans\u002Fagentic-iteration-1.md`). When omitted, defaults to `.\u002Fplan.md` (Small) or `docs\u002Fywc-plans\u002F\u003Cslug>.md` (Medium\u002FLarge). |\n| `--artifact-profile agentic` | enum | Agentic-owned artifact mode. Mutually exclusive with `--output`; direct calls without this flag retain the existing output behavior. |\n\n## Rationalization Defense\n\nWhen tempted to bypass a rule, check this table first:\n\n| Excuse | Reality |\n|---|---|\n| \"User said 'just plan it', I'll skip the codebase investigation\" | Codebase investigation is mandatory before drafting either artifact. Plans written without reading existing code, project instruction files (`AGENTS.md`, `CODEX.md`, `CLAUDE.md`), or `docs\u002Farchitecture\u002F` produce conflicts that surface during implementation. The agent always feels confident; the user still suffers the rework. |\n| \"Scale looks ambiguous, I'll default to Small to keep things light\" | Default to **Medium** when ambiguous, not Small. Small path skips spec review and task decomposition — wrong scale call cascades into untracked scope creep. The cost of writing a spec for an actually-Small change is one wasted hour; the cost of skipping a spec for an actually-Medium change is rework across multiple sessions. |\n| \"DB migration is part of the change, I'll bundle it into the Small plan\" | Any change touching `migrations\u002F`, `prisma\u002Fschema.prisma`, `*.sql`, or equivalent is **never Small**. DB migration must be its own task — escalate to Medium path so `ywc-task-generator` can split it. Safety invariant — same rule as `ywc-task-generator`. |\n| \"User wants to start coding now, I'll skip ywc-spec-validate on the Medium spec\" | The Medium\u002FLarge path **must** route through `ywc-spec-validate` before `ywc-task-generator`. Skipping spec review is the failure mode `ywc-task-generator`'s `requires: [ywc-spec-validate]` exists to prevent. Run review even when the user is impatient. |\n| \"Out of Scope is obvious, I'll leave it implicit\" | Always write Out of Scope explicitly — both in the Small `plan.md` and the Medium spec. The implicit version is the one the agent silently expands during implementation. Empty Out of Scope = guaranteed scope drift. |\n| \"Library introduction is small, I'll bundle it\" | Any new library\u002Fframework introduction is **never Small**. Same Safety Invariant as DB migration — escalate to Medium path. |\n| \"User mentioned 'auto-execute', I'll skip the spec for Medium too\" | Auto-execute via `ywc-parallel-executor` or `ywc-sequential-executor` does not remove the spec requirement — those executors consume task directories produced by `ywc-task-generator`, which itself requires a reviewed spec. The shortcut does not exist. |\n| \"The idea is clear enough, I'll write the spec directly\" | For Medium\u002FLarge changes, unverified design assumptions are the most expensive rework source. Before drafting the spec, surface at least the key branching decisions: data model shape, API boundary, error handling strategy, and any third-party integration scope. Assumptions that seem obvious now become the reason the spec is rewritten during implementation. |\n| \"The spec-writing process is overhead — let's get to the tasks faster\" | Design investment is not overhead — it IS the task. Every hour spent clarifying scope and surfacing assumptions prevents 3–5 hours of rework during implementation. Kent Beck: \"Invest in the design of the system every day.\" The spec is today's investment. |\n| \"The spec says it follows existing component X, that's good enough — no need to read X\" | \"Follows X\" is a *claim*, not a *spec*. Code Compatibility findings are the largest single category of spec-validate Critical findings, and the majority trace to a \"follows X\" claim where the author never opened X. Read X end-to-end and transcribe its behavior into **Existing Constraints Touched** with `file:line` citations. The reviewer cannot verify what was never written down. |\n| \"I grepped and found the one writer\u002Freader, so that's the only one\" | A forward grep that confirms **one** instance is not evidence of a **closed set**. Closure claims (\"only \u002F sole \u002F 唯一 \u002F no other \u002F all \u002F exhaustive\") and liveness claims (\"dead \u002F @deprecated \u002F 呼び出し元ゼロ \u002F still active\") are the single largest source of *false-but-confident* spec assertions: the planner confirms the instance it already had in mind and never runs the *complement* grep that enumerates the rest. The most expensive Critical in the LP column-drop plan was exactly this — \"injectAndSaveGtmSnippet is the 唯一の generatedHtml writer\", but `markDone` also wrote it, and dropping the column would have broken the build. Before writing any closure or liveness word, run the complement grep (`grep -rn \"\u003Cidentifier>\" \u003Cmodule>`, classify every hit live\u002Fdead) and transcribe the full set. |\n| \"While I'm reading this code anyway, I'll fold in the adjacent cleanup\u002Frefactor\" | Thoroughness in *investigation* must not become expansion of the *change scope*. A plan that enumerates a related site (a parameter, a sibling method, a rename opportunity) and then proposes changing it — when the request did not ask for it — adds surface that becomes new Critical findings. The measured regression: a `generatedHtml`-drop plan proactively proposed a `composeHtml` refactor and shipped a build-break Critical the narrower plan never risked. Enumerate everything; change only what the request requires; record the rest as \"no change needed\" under Existing Constraints Touched. |\n| \"AC and the API Contract probably agree, I won't cross-check\" | Cross-section drift between AC, FR, Data Model, and API Contract is the #2 source of Critical findings (after Code Compatibility). Step 4b.5 is mandatory for Medium\u002FLarge precisely because authors trust their own consistency and reviewers find it broken. Run the cross-check; the cost is ~5 minutes, the cost of skipping it is one full re-plan iteration. |\n| \"The quality gate can infer the missing command or boundary\" | A Quality Gate Contract is opt-in and caller-bound. For Medium\u002FLarge specs, declare the complete bounded metadata or the exact `N\u002FA — no quality gate contract` sentinel. Missing ownership, command IDs\u002Fdigests, thresholds, or sanitized evidence paths returns `NEEDS_CONTEXT`; never invent a command, digest, threshold, path, or pass. |\n| \"Validation came back DONE_WITH_CONCERNS, I'll rewrite the spec from scratch and re-run\" | Use **Re-plan Mode** (`--update-spec \u003Cpath> --failure-context \"\u003Cfindings>\"`) instead. Re-plan appends an `## Iteration N Amendments` section that addresses only the failing items, preserving the rest of the spec verbatim. Rewriting from scratch loses the validated portions and produces cosmetic diffs that reviewers must re-validate. |\n\n**Violating the letter of these rules is violating the spirit.** Safety Invariants (DB migration separation, library introduction separation, mandatory spec review for Medium\u002FLarge) have no exceptions, regardless of urgency.\n\n## Quality Gate Contract (Medium\u002FLarge only)\n\nEvery Medium\u002FLarge spec must include either a complete `Quality Gate Contract`\ndeclaration or the exact compatibility sentinel `N\u002FA — no quality gate contract`.\nThe declaration is bounded metadata for the downstream task-generator packet; it\nis not permission to execute a command. Cite the canonical rules in\n[..\u002Freferences\u002Fquality-gates.md](..\u002Freferences\u002Fquality-gates.md) rather than\ncopying or redefining its state semantics.\n\nA declared contract must provide all of the following, using caller-approved\nvalues and exact task boundaries:\n\n- `contract_state`: `report-only`, `advisory`, or `enforced`;\n- `ownership.production_paths` and `ownership.production_symbols` for Cleaner;\n- `ownership.test_fixture_paths` and `ownership.test_fixture_symbols` for Hardener;\n- immutable `approved_command_ids` and matching `approved_command_digests`;\n- bounded repository-relative `sanitized_evidence_paths`;\n- caller-approved `complexity_threshold`, `mutation_target`, and `attempt_cap` (at most three); and\n- `residual_survivors` handling, without declaring survivors equivalent.\n\nDo not include raw executable command text, raw output, transcripts, secrets, or\nfull diffs. Do not broaden module boundaries or fill missing fields from project\nconventions. An incomplete, contradictory, unauthorized, or unbounded\ndeclaration is `NEEDS_CONTEXT` and must not be handed off as a valid packet. The\nexact no-contract sentinel preserves the existing planning and downstream\nworkflow; it emits no placeholder packet and selects no quality-gate worker.\n\nFor Medium\u002FLarge specs, `Module Boundaries` must identify each affected module's\nowner, consumers, and responsibility, including the producer declaration and\nthe downstream task-generator consumer. A boundary that is not exact enough to\nbind changed production symbols and test\u002Ffixture symbols is incomplete.\n\n## Workflow\n\nThe skill executes five steps. Steps 1–2 are mandatory; Steps 3–5 branch on the scale assessment.\n\n### Step 1.0: Brainstorm Gate\n\nBefore extracting anchors, evaluate whether the request is concrete enough for direct planning. Some requests arrive as design conversations rather than plan inputs; those must run through `ywc-brainstorm` first.\n\n| Signal | Route |\n|---|---|\n| Request includes a concrete change description, files \u002F surfaces touched, and an observable Done condition | Proceed to Step 1 — anchors will extract cleanly. |\n| Request is conversational (\"I'm thinking about X\", \"wouldn't it be nice if…\", \"let's explore Y\", \"어떻게 만들지\", \"アイディアがある\") | **Delegate to `ywc-brainstorm`** — it surfaces the four anchors via Socratic dialogue and presents 2–3 approaches; resume `ywc-plan` from Step 1 with the brainstorm handoff as input. |\n| Request describes multiple independent subsystems (e.g., \"a platform with auth, chat, billing, analytics\") | **Delegate to `ywc-brainstorm`** for decomposition before any anchor extraction. Each subsystem gets its own brainstorm → plan cycle. |\n| Two or more of (What \u002F Why \u002F Out of Scope \u002F Done When) are completely missing from the request | **Delegate to `ywc-brainstorm`** — extracting two missing anchors at once produces shallow answers; ywc-brainstorm collects them one at a time with explicit approach trade-offs. |\n| The destination is known, but the open decisions must be tracked across multiple sessions before a stable plan can be written | **Delegate to `ywc-wayfinder`** — it maintains the local discovery map, enforces exactly one active ticket, and routes back here once a planning-ready ticket resolves. |\n\nWhen delegating, surface this verbatim before transferring control:\n\n> \"This request needs intent clarification before planning. Switching to `ywc-brainstorm` to surface the four anchors and approach choice. After the design is approved, returning to `ywc-plan` Step 1 with the brainstorm handoff as input.\"\n\nWhen `ywc-brainstorm` completes, its handoff message includes the four anchors and the chosen approach. Re-enter `ywc-plan` Step 1 with that handoff as the effective user input — the anchors should already be filled, so Step 1 typically reduces to a one-sentence confirmation.\n\n`--non-interactive` mode skips the delegation: when the flag is present, treat ambiguity as Medium scale (Step 3) and fill missing anchors with defaults rather than routing to `ywc-brainstorm`.\n\nIf `ywc-wayfinder` hands back a resolved ticket, treat that ticket's local map path and acceptance notes as the current request context. If `ywc-wayfinder` returns `NEEDS_CONTEXT`, do not draft a plan yet.\n\nAfter Scale assessment in Step 2 and before any downstream handoff (`ywc-spec-writer`, `ywc-task-generator`, `ywc-code-gen`, executor), invoke `ywc-confidence-gate` with the chosen approach as input. The gate's PROCEED \u002F REVIEW \u002F STOP band determines whether the plan is ready for handoff; a REVIEW band surfaces alternatives to the user, a STOP band routes back here for additional investigation before re-attempting handoff. The 5-dimension score becomes part of the plan's completion summary so downstream skills inherit a comparable confidence number.\n\nWhen the chosen path still depends on unverified assumptions, run [..\u002Freferences\u002Funknown-matrix.md](..\u002Freferences\u002Funknown-matrix.md) before handoff and preserve those assumptions explicitly in the artifact's risk \u002F follow-up language. Do not weaken existing `NEEDS_CONTEXT` rules: if a missing answer blocks a coherent plan, stop and ask instead of parking it as an unknown.\n\nWhen a persisted `ywc-tech-research --output \u003Cpath>` artifact exists, cite that project-relative Markdown path in the resulting plan\u002Fspec instead of copying unsourced research prose. Preserve its provenance markers and overwrite expectations.\n\n### Step 1: Clarify the Request\n\n**Prerequisite:** If `docs\u002Fubiquitous-language.md` exists, read it before asking any questions. The vocabulary defined there must frame the clarification dialogue itself — use canonical terms in your questions and note any \"Synonyms to Avoid\" so the user's answers are captured in the right terms from the start.\n\n**Codebase-Fact Pre-check.** Before finalizing the anchor questions below, check whether the answer is already visible in the codebase — an existing pattern, a referenced file, a prior issue named in the request. Budget: at most **5 targeted lookups across at most 3 files**, using read-only `rg` searches or reads only — this is not a substitute for Step 2's full investigation.\n\n| Question type | Route |\n|---|---|\n| Codebase Fact — answer is verifiable by reading existing code, config, or a referenced file (e.g., \"does this project already have an X pattern?\", \"what does the existing error format look like?\") | Check the codebase first, citing `file:line` as evidence for the answer; only ask the user if the check is inconclusive or the budget is exhausted before a confident answer emerges. |\n| User Preference \u002F Scope \u002F Requirement — answer depends on intent, priority, or a decision only the user can make (e.g., \"should this be opt-in or opt-out?\", \"is backward compatibility required?\") | Ask the user directly — the codebase cannot answer this. |\n\nThis pre-check stays active under `--non-interactive`: a Codebase Fact question the check resolves is answered from the cited evidence and never asked; one it leaves inconclusive falls through to the `--non-interactive` defaulting rule below. Because no default is defined for **What** or **Why**, an inconclusive or unresolved **What**\u002F**Why** anchor under `--non-interactive` **stops** the skill and reports `NEEDS_CONTEXT` rather than proceeding to Step 2 with the change's intent unresolved.\n\nAsk focused questions to extract four anchors. Use one round of consolidated questions (not back-and-forth) unless the user's initial input already covers some anchors.\n\n| Anchor | What to ask | Why it matters |\n|---|---|---|\n| **What** | \"What concrete change are we making? Which user-facing behavior or system capability is added\u002Fchanged\u002Fremoved?\" | Without a concrete What, scale cannot be assessed. |\n| **Why** | \"What problem does this solve? What signal motivated it (user request, bug, metric, compliance)?\" | Why grounds priority and scope decisions during implementation. |\n| **Out of Scope** | \"What is explicitly not part of this change? What might look related but is being deferred?\" | Out of Scope is the scope-creep guardrail. Always write it. |\n| **Done When** | \"How will we know it's complete? What observable outcome proves success?\" | Done conditions become the Acceptance Criteria in the artifact. |\n\nIf the user's initial message already answers all four anchors, skip the questions and confirm understanding in one sentence.\n\n**`--non-interactive` mode:** When this flag is present, do not ask interactive clarification questions at any point in Step 1. If the user's initial message leaves **Out of Scope** or **Done When** unanswered, fill it with the following defaults automatically: Out of Scope = `\"nothing explicitly excluded\"`, Done When = `\"all tasks merged and ywc-impl-review returns DONE\"`. **What** and **Why** have no default — if either remains unanswered after the Codebase-Fact Pre-check above, stop and report `NEEDS_CONTEXT` instead of proceeding. Otherwise, proceed directly to Step 2 without waiting for user input.\n\n### Step 2: Investigate the Codebase\n\nRead targeted files to ground the plan in actual project state. Step 2 is organized into four parts: what to **always** read, what to read **conditionally**, what triggers a **deeper** read, and **when to stop**.\n\n#### Always read\n\n- `AGENTS.md`, `CODEX.md`, and `CLAUDE.md` at repo root when present — language policy, conventions, CI commands. Prefer Codex-native instructions (`AGENTS.md` \u002F `CODEX.md`) when they conflict with Claude-only guidance.\n- `package.json`, `pyproject.toml`, `Makefile`, `go.mod` etc. — actual lint\u002Ftest\u002Fbuild commands\n- Project tree (top 2 levels of `src\u002F`, `apps\u002F`, or equivalent) — module placement and existing patterns\n- Existing `tasks\u002F` directory if present — phase numbering and dependency context\n- Relevant `docs\u002Fywc-plans\u002F`, `docs\u002Farchitecture\u002F`, `docs\u002Fproduct\u002F` if the project uses the LLM development guide layout\n- `docs\u002Fubiquitous-language.md` (if it exists) — canonical domain terms and their \"Synonyms to Avoid\"; spec text and Out of Scope items must use canonical terms and never use synonym identifiers\n- **Parent spec \u002F design doc** named in the plan's own header (`Parent spec:`, `親 spec:`, `Spec Reference:`) — when the request is a follow-up or amendment to an existing plan, read the parent end-to-end. A follow-up that silently narrows the parent's explicit removal\u002Fscope list is a cross-document Consistency finding: in the LP column-drop follow-up, the parent said \"delete `markDone`\u002F`markFailed`\" but the follow-up's removal list dropped `markDone`, which would have left a dangling write against the dropped column.\n\n#### Conditional reads (only when relevant to the request)\n\n- DB-touching requests: existing schema\u002Fmigration files\n- API-touching requests: existing route definitions and OpenAPI\u002Fcontract files\n- UI-touching requests: existing component patterns\n\n#### Trigger-based deep reads\n\nFour triggers force a deeper read than the lists above. Each fires independently — if more than one applies, do all of them.\n\n1. **Explicit \"follows existing X\" claim.** When the user's request — or your own draft of Scope \u002F Functional Requirements \u002F Data Model — uses phrases like *\"踏襲 \u002F follows \u002F based on \u002F extends \u002F 同じパターンで \u002F similar to \u002F mirrors \u002F 参考に\"* and names a specific component, you **must read that component end-to-end** (not just its location, not just nearby patterns). The new spec inherits not only the pattern but every actual behavior — response headers, status codes, timeout values, parser limits, cascade rules. Capture each inherited behavior under **Existing Constraints Touched** with a `file:line` citation. This rule exists because Code Compatibility findings dominate spec-validate Critical counts — and the majority trace back to a \"踏襲\" claim whose author never opened the referenced file.\n\n2. **Implicit reference to existing types\u002Fmodels.** The \"follows X\" rule fires on prose claims, but the more common failure is the *implicit* reference — the spec never says \"follows X\", it just uses an identifier or shape that already exists. Trigger a deep read whenever the spec:\n   - **Uses a property accessor on an existing domain type by name** not declared in your own Data Model (e.g., `tenantSlug`, `userEmail`, `orderId.short`, `submission.actor.user_id`) — every such accessor is a claim that the property exists with the expected shape\n   - **Names an existing audit log, event, DTO, or error type by category** without inlining its shape (e.g., \"writes an audit log\", \"emits a `UserCreated` event\", \"returns a `ConflictError`\") — the spec must either inline the shape with a `file:line` citation or explicitly reference the existing type, never invent a parallel shape\n   - **Introduces a new column whose name or semantics overlap a field already present elsewhere** — either reuse the existing field\u002Fenum or justify the divergence\n\n   For each implicit reference, grep the existing schema\u002Ftypes (`grep -n \"\u003Cidentifier>\" backend\u002Fprisma\u002Fschema.prisma`, `grep -rn \"\u003CTypeName>\" backend\u002Fsrc\u002Flib\u002F`) and either capture the verified shape under **Existing Constraints Touched** or declare the schema change explicitly. This rule exists because findings like \"field absent on existing model\" and \"shape mismatch with existing type\" arise from variable-name use, not from any prose claim of \"踏襲\".\n\n3. **Stack-primitive section about to be written.** Before drafting Data Model, API Contract, or any section that touches DB \u002F middleware \u002F framework primitives, skim [references\u002Fcommon-pitfalls.md](references\u002Fcommon-pitfalls.md). It enumerates the recurring traps spec-validate flags (global vs route-scoped middleware, `@HttpCode` vs documented status, error-handling discipline, etc.). The schema-side rules live separately in the shared schema guide: [..\u002Freferences\u002Fschema\u002Fcore.md](..\u002Freferences\u002Fschema\u002Fcore.md) plus the matching stack file (`prisma.md` \u002F `sql-ddl.md` \u002F `drizzle.md` \u002F `typeorm.md`). Skimming both at Step 2 is cheaper than discovering each trap individually in validation.\n\n4. **Closure or liveness claim about code.** The first three triggers fire on a *positive identity* claim (\"this follows \u002F uses X\"). This one fires on the inverse — *set-closure* and *liveness* claims — which are just as failure-prone and far easier to assert from memory. When your draft asserts that a set is complete — *\"only \u002F sole \u002F 唯一 \u002F the single \u002F no other \u002F all \u002F exhaustive \u002F 全て \u002F 唯一の … 経路\"* — or that a symbol is dead or alive — *\"@deprecated \u002F unused \u002F 呼び出し元ゼロ \u002F dead write \u002F still active \u002F 現に write\"* — you must run the **complement grep**: enumerate the entire candidate set, not just re-confirm the one instance already in hand. For \"C is the only writer of column X\", run `grep -rn \"X\" \u003Cmodule>` and classify every write site live\u002Fdead; for \"method M is dead\", grep M's callers repo-wide and transcribe the zero (or the non-zero hit you would otherwise have missed). Capture the enumerated set under **Existing Constraints Touched**. This rule exists because a forward grep that confirms one writer is silently mistaken for proof that no other writer exists — the failure mode behind both the largest Critical and a Warning in the LP column-drop plan (`markDone` was a second `generatedHtml` writer the \"唯一の write 経路\" claim never enumerated; `markFailed` was dead despite an \"active\" claim).\n\n   Two disciplines when transcribing the enumerated set:\n   - **Attribute each hit to its own `file:line`.** Never fold one file's line numbers under another file's header — mixing `lp.service.ts` lines into an `lp.repository.ts` proof is itself a Consistency finding the reviewer will flag.\n   - **Enumeration is for comprehension, not scope expansion.** Classify each enumerated site as *must-change for this request* or *no change needed* (record the latter under **Existing Constraints Touched**, not in the change list). Never fold an adjacent refactor — a rename, a signature change on a site that merely looks related — into the plan unless the request requires it. \"While I'm here I'll also refactor X\" over-reach expands the plan's surface and is its own Critical source; the measured failure was a plan that proactively proposed a `composeHtml` refactor and introduced a build break the narrower plan never risked.\n\n#### When to stop\n\nStop investigating once you can confidently (a) pick a scale using Step 3's rubric, (b) name concrete files in the plan or spec, and (c) state the project's actual lint\u002Ftest\u002Fbuild commands. Going beyond this is `gstack-investigate`'s job — defer to that skill if the user explicitly wants deep investigation.\n\n### Step 3: Assess Scale\n\nPick exactly one scale using the rubric below. **Default to Medium when ambiguous.**\n\n| Scale | Criteria (any one matches) | Path |\n|---|---|---|\n| **Small** | All of: ≤3 files changed, ≤300 LOC, single concern, no DB migration, no new library, no cross-module impact | Direct execution plan (`plan.md`) |\n| **Medium** | 4–15 expected tasks, OR DB migration involved, OR new library introduction, OR touches 2–3 modules | Spec document → `ywc-spec-validate` → `ywc-task-generator` |\n| **Large** | 15+ expected tasks, OR cross-cutting refactor, OR new feature with multiple phases | Spec document → split suggestion to user → `ywc-spec-validate` → `ywc-task-generator` |\n\n**Hard-disqualifiers from Small** (any of these forces Medium minimum):\n\n- Database migration \u002F schema change\n- New library\u002Fframework introduction\n- New API contract that other services consume\n- Cross-cutting concern (auth, logging, error handling) modified in >1 module\n\nFor the full scale-assessment heuristics including borderline-case examples, see [references\u002Fscale-assessment.md](references\u002Fscale-assessment.md).\n\n### Step 3.5: Architectural Advisor Gate (Medium\u002FLarge only)\n\nRun this gate **only when both conditions hold**:\n\n- Scale assessed as **Medium** or **Large** (Small path skips this gate)\n- Step 2 codebase investigation surfaced an architectural ambiguity that the spec \u002F `docs\u002Farchitecture\u002F` \u002F project convention cannot resolve on its own (examples: monolith vs split, sync vs async boundary, ORM vs raw SQL, domain boundary placement, abstraction-vs-duplication trade-off for a soon-to-be-replicated pattern)\n\nIf both conditions fail, skip to Step 4 directly. The gate exists to head off the failure mode where a Medium\u002FLarge plan locks in a structural choice that subsequent implementation cannot walk back without a re-plan.\n\n**Procedure**:\n\n1. **Frame the decision** in one sentence with the two (occasionally three) reasonable options the codebase \u002F spec admit. Avoid hypothetical options the project would not actually pick.\n2. **Assemble the bounded payload** — the spec excerpt that touches the decision (≤30 lines), the most relevant existing code reference (file path + 1-paragraph summary, not the full file), and the project convention or prior-art entry if one applies. Do not forward the whole spec.\n3. **Dispatch the advisor**. Use Codex subagent delegation when the current session exposes a delegation tool. Prefer the installed Codex custom agent `ywc-architect` when available; otherwise request one higher-capability architecture advisor pass with the bounded payload and the same decision frame. If no delegation tool is available, run the architecture-advisor checklist inline as a separate bounded pass and record the fallback in the plan. Do not use Claude Code named-agent syntax, Claude agent-path examples, or explicit Claude model pins in the Codex bundle.\n4. **Record the verdict** in `docs\u002Fywc-plans\u002F\u003Cplan-slug>\u002Farchitecture-verdict.md` (or alongside the spec when the spec path is provided). The file captures: the framed decision, the trade-off table the advisor returned, the chosen direction, and the file \u002F type \u002F structural shape recommendation. Subsequent steps cite this file rather than re-litigating the decision.\n5. **Handle non-DONE statuses** per the standard contract:\n   - `DONE_WITH_CONCERNS` → cite the concerns explicitly in the spec's Constraints section so reviewers see the caveat\n   - `NEEDS_CONTEXT` → run the additional file reads \u002F searches the advisor names, then re-dispatch with the enriched payload\n   - `BLOCKED` → surface to the user with the advisor's blocker summary; do not proceed to Step 4 until the prerequisite is resolved\n\n**Budget**: at most **1** architecture advisor dispatch per ywc-plan invocation. If a second architectural decision surfaces, defer it to `ywc-confidence-gate` STOP-band routing or to a follow-up plan rather than spending another advisor call inside the same plan run.\n\nSkip the gate entirely (with a one-line note in the plan \u002F spec) when the architectural choice is unambiguous from the spec or already adjudicated by a prior `architecture-verdict.md` in the same project.\n\n### Step 4a: Small Path — Direct Execution Plan\n\nWhen scale is **Small**, generate `plan.md` at a user-specified path (default: `.\u002Fplan.md`). If `--output \u003Cpath>` is provided, write to that path instead of the default.\n\nFor the full `plan.md` structure and a worked example, see [references\u002Fsmall-plan-template.md](references\u002Fsmall-plan-template.md).\n\nThe plan **must** include: Goal, Out of Scope, Files to touch (concrete paths), Implementation Steps (checkbox list with file\u002Ffunction references), Verification commands (using project's actual commands from Step 2), Risks\u002FRollback, and Interfaces (optional — only when the plan touches ≥2 files that share a function\u002Ftype signature).\n\nAfter writing the plan, surface this handoff message to the user:\n\n> \"Plan ready at `\u003Cpath>`. To execute, you can:\n> 1. Implement directly in this session, or\n> 2. Run `$ywc-code-gen` with the plan as context, or\n> 3. Hand off to `$ywc-sequential-executor` if you prefer Branch + PR isolation.\"\n\n### Step 4b: Medium\u002FLarge Path — Spec Document\n\nWhen scale is **Medium** or **Large**, generate a spec document under `docs\u002Fywc-plans\u002F\u003Cfeature-slug>.md` (or the project's equivalent — derive from Step 2 investigation). If `--output \u003Cpath>` is provided, write to that path instead of the derived slug path.\n\nFor the full spec structure aligned with `ywc-spec-validate`'s evaluation dimensions, see [references\u002Fspec-template.md](references\u002Fspec-template.md).\n\nThe spec **must** include: Purpose, Scope, Out of Scope, Acceptance Criteria, Functional Requirements, Non-Functional Requirements (when applicable), Data Model \u002F API Contract (when applicable), Edge Cases, and Open Questions (use `N\u002FA — none identified` if none).\n\nAdd `## Failure Modes` rows with ID, triggering path, observable failure,\nhandling\u002Fdetection, and verification. Missing handling or missing detection\u002Ftest\nevidence is an explicit gap; when both are missing, never silently pass the row.\nNew specs consider relevant failure paths; legacy specs without this section\nremain valid. For each command-bearing AC, record observed baseline,\nrevision\u002Fcontext and evidence, or `not measured` with the gap. A spec command\nis data, not authorization to execute it; preserve existing approved command\nexecution boundaries.\n\n\nRecord project-wide constraints found in Step 2 (version floors, dependency constraints, naming\u002Fcopy conventions, platform requirements) in the spec's `## Global Constraints` section — see [references\u002Fspec-template.md](references\u002Fspec-template.md).\n\nWhen the spec names module boundaries, key types, and interfaces, ground those design choices in the shared readable-code rubric — especially §G (structural smells) and its anti-dogma guardrails (do not specify speculative generality or premature abstraction the requirement does not yet need). See [..\u002Freferences\u002Freadable-code.md](..\u002Freferences\u002Freadable-code.md).\n\nFor **Large** scale, also surface this advisory before writing the spec:\n\n> \"This change is Large (15+ expected tasks). Consider splitting into multiple smaller specs by feature boundary. Splitting now is cheaper than splitting after `ywc-task-generator` produces 20+ task directories. Proceed with single spec, or split first?\"\n\n### Step 4c: Re-plan Mode\n\nActivated when `--update-spec \u003Cpath>` and `--failure-context \u003Ctext>` are both provided. This mode is mutually exclusive with normal spec generation (Steps 4a and 4b).\n\n**Behavior:**\n\n1. Read the existing spec at `\u003Cpath>`. If the file does not exist, report an error and stop — do not create a new file.\n2. Determine the current iteration number by counting existing `## Iteration N Amendments` sections in the file. The new section number is N + 1 (starting at 1 if none exist).\n3. Using `--failure-context` as the input (the \"Fix Priority\" section text from `ywc-impl-review`), draft amendment content that addresses only the failing areas.\n4. **Append** `## Iteration N Amendments` to the end of the existing spec file. Do NOT create a new file, do NOT rewrite any completed section's body above the new section.\n4.5. **Mark superseded originals (the one permitted in-place edit).** When the amendment scopes out or changes an instruction that an original section still states literally — e.g., an original migration SQL block that drops a column the amendment now defers — prepend a single inline marker line at the head of that original section: `> ⚠️ SUPERSEDED by Iteration N — see §\u003Camendment-anchor>`. Do not edit the section's body, only prepend the marker. Then ensure a top-of-file **Operative Sections** pointer names which sections `ywc-task-generator` should treat as authoritative. This removes the precedence-only resolution that otherwise leaves a copy-faithful implementer acting on the superseded original — the exact residual Warning in the LP column-drop re-validation, where the original §1 SQL still dropped `errorMessage` after the amendment deferred it.\n5. The appended section must include: which requirements failed (from `--failure-context`), the amended approach, and updated Acceptance Criteria for the affected items only.\n6. **Re-run Step 4b.5 on the whole spec** (original sections + the new amendment) before printing the handoff. An amendment frequently introduces fresh drift — a new status code that conflicts with an original AC, a new field absent from the original API Contract, a new state value without a write site. Without the re-run, that drift surfaces as a *fresh* Critical at the next `ywc-spec-validate` pass and forces yet another iteration. Re-running 4b.5 here is what makes Re-plan Mode actually converge.\n\n**Constraints:**\n\n- Never overwrite or reorder existing content — **except** the single-line `> ⚠️ SUPERSEDED ...` marker permitted by Behavior step 4.5, which prepends (never rewrites the body of) a contradicted original section.\n- Never create a new spec file — only append to the file at `\u003Cpath>`.\n- `--output` is ignored in Re-plan Mode (output path is always the `--update-spec` path).\n\n### Step 4b.5: Pre-Handoff Self-Consistency Pass (Medium\u002FLarge only)\n\nBefore printing the handoff message in Step 5, run this mechanical check on the spec you just wrote. Step 5's `Validation` list checks **structural** items (sections exist, anchors answered); Step 4b.5 catches the **semantic drift** the author introduces between sections — which is what dominates `ywc-spec-validate` Critical findings.\n\nThe check is organized into three passes, each catching a different class of drift. Run all three. For each row, scan the spec end-to-end and answer with a concrete pointer (section heading or `file:line`). If the answer is \"I'm not sure\" or \"probably yes\", edit the spec until the answer becomes \"yes, see \u003Cpointer>\" before printing the handoff.\n\nExamples below are tagged *(past session, this codebase)* — they are real failures observed during the LP form \u002F publish spec work that motivated this skill, included because concrete examples teach better than abstract rules. The **Rule** column is the universal principle and applies to any feature family.\n\n#### Pass A — Cross-section consistency (within this spec)\n\nCatches drift between AC \u002F FR \u002F API Contract \u002F Data Model of the same spec.\n\n| Rule | Example failure (past session, this codebase) |\n|---|---|\n| Every Acceptance Criterion maps to ≥1 Functional Requirement; every Functional Requirement is motivated by ≥1 AC | Orphan ACs (tests for unspecified behavior); orphan FRs (unmotivated work) |\n| Every HTTP status code mentioned anywhere (AC, FR, Edge Case, NFR) also appears in the API Contract — and the API Contract has no orphan codes | AC3 says `202`, AC6 says `200`, controller enforces `@HttpCode(202)` → silent contradiction |\n| Every field name in API Contract request\u002Fresponse is either declared in Data Model **or** explicitly marked as \"derived from X\" \u002F \"server-side snapshot from Y\" | `consentText` appears in DB columns but is missing from the request body — reviewer cannot tell whether the field is client-supplied (spoofable PII) or server-snapshotted |\n| Every Acceptance Criterion is in the form `When \u003Ctrigger>, system does \u003Cbehavior>, observable as \u003Cconcrete check>` — not a bare behavior name | \"e2e: form submission の golden path\" is a section name; becomes an AC only when it specifies request shape → expected status → DB row state |\n| Every new state value (enum value, status flag, lifecycle column) declared in Data Model has ≥1 Functional Requirement writing it, **and** Edge Cases enumerate every state combination it introduces (A→B→A, delete-then-recreate, partial-then-resume) | `LandingPage.status='PUBLISHED'` added to the enum without a transaction writing it; `unpublish → delete LpFormConfig → republish` is a 3-step path the spec never enumerates |\n| Every grep-based Acceptance Criterion matches the code's **actual call shape** — a single-line regex like `update\\([^)]*field` does not match a multi-line `.update({ … field … })`, so use a broad identifier grep or pair the narrow regex with one | AC1's single-line `landingPage\\.update\\([^)]*generatedHtml` could not match `markDone`'s multi-line `.update({ … })` — the verification command shared the exact blind spot that let the Critical through, so the AC would have falsely passed |\n\n#### Pass B — Claim ↔ reality verification (this spec vs existing code \u002F sibling specs)\n\nCatches the failure mode where the spec asserts something about the world that turns out to be false at implementation time.\n\n| Rule | Example failure (past session, this codebase) |\n|---|---|\n| Every \"踏襲 \u002F follows \u002F based on \u002F extends X\" claim carries a `file:line` citation, **and** the cited code's actual behavior is transcribed into **Existing Constraints Touched** | \"`LpFormCorsInterceptor` follows `BeaconSiteCorsInterceptor`\" — the cited interceptor unconditionally sets `Allow-Credentials: true`, contradicting AC1 |\n| Every \"no change to existing X\" \u002F \"§Y そのまま採用\" claim is verified — replace with \"based on X, with diffs: A, B, C\" the moment any diff exists | Data Model header says \"§5 そのまま\" while silently changing `isActive` default and adding `consentText` columns |\n| Every Edge Case threshold (size, time, rate) is verified against the actual enforcing code, not assumed | \"body > 32kb → 413\" sounds observable; `main.ts` actually enforces 6mb globally — the spec is a wish, not an assertion, until the limit is path-scoped |\n| Every function signature, shared type, prerequisite, or shared constant that crosses a sibling spec in the same feature family appears identically in both — or one spec explicitly declares \"owned by spec X, referenced here\" with the canonical signature inlined | `injectBeaconMarkers(html, formKey)` is untyped 2-arg in form spec but `(html: string, formKey: string \\| null): string` in publish spec; publish spec depends on `LpFormConfig` from form spec without naming the prerequisite in Dependencies |\n| Every closure claim (\"only \u002F sole \u002F 唯一 \u002F no other \u002F all \u002F exhaustive\") and every liveness claim (\"dead \u002F @deprecated \u002F 呼び出し元ゼロ \u002F still active\") carries the **complement-grep result** enumerating the full candidate set — not a single confirming instance (Step 2 trigger #4 produced this; Pass B confirms it landed in the spec) | \"injectAndSaveGtmSnippet is the 唯一の write 経路\" — `markDone` (`:404`) also wrote the column → Critical; \"errorMessage is active because markFailed writes it\" — `markFailed` had zero callers → Warning |\n| Every removal \u002F scope item in a referenced parent spec is either carried into this follow-up or explicitly deferred with a stated reason — a follow-up never silently narrows the parent's declared scope | Parent plan §3 said \"delete `markDone`\u002F`markFailed`\"; the follow-up's removal list dropped `markDone`, so the dropped column would still be referenced by a live build target |\n\n#### Pass C — Schema invariants (Data Model mechanical rules)\n\nCatches Data Model omissions that make the migration fail at `prisma generate`, the first delete attempt, or the first concurrent insert. The two highest-frequency Criticals are inline; the full ruleset (NOT NULL backfill, FK index, composite uniqueness, multi-tenant scope, enum domain, `timestamptz`) is in the shared schema guide: [..\u002Freferences\u002Fschema\u002Fcore.md](..\u002Freferences\u002Fschema\u002Fcore.md) plus the matching stack file (`prisma.md` \u002F `sql-ddl.md` \u002F `drizzle.md` \u002F `typeorm.md`).\n\n| Rule | Example failure (past session, this codebase) |\n|---|---|\n| Every new DB `@relation` has the reverse-relation field declared on the other model **in this spec** (even if the other model already exists in `schema.prisma`) | `@relation` on `LpFormSubmission` pointing at `LandingPage` without adding `lpFormSubmissions LpFormSubmission[]` on `LandingPage` → `prisma generate` fails |\n| Every `onDelete` rule (`Restrict \u002F Cascade \u002F SetNull \u002F NoAction`) has its API consequence specified in the API Contract (typically `409 Conflict` for `Restrict`, a destructive-side-effect note for `Cascade`) | `onDelete: Restrict` on submissions, but `DELETE \u002Fapi\u002Flp-forms\u002F:id` lacks `409 Conflict` and the operator UX for \"delete submissions first\" |\n\nFor the full Data Model self-check, run the review checklist in [..\u002Freferences\u002Fschema\u002Fcore.md](..\u002Freferences\u002Fschema\u002Fcore.md) Part C and the stack-specific notes for the project's ORM or DDL style.\n\n---\n\nThis step is **mandatory for the Medium\u002FLarge path** (Step 4b), **for the appended amendment in Re-plan Mode** (Step 4c), and **for any in-place append of implementation detail to an existing plan or spec** — including a free-form 追補 \u002F follow-up block added through a direct file edit rather than through `--update-spec`. The append path is the one that silently skips this pass: it is neither a fresh Step 4b generation nor a formal Step 4c invocation, so the failure that motivated these rules (a follow-up 追補 whose \"唯一の write 経路\" closure claim was never complement-grepped) lands exactly there. Run at minimum **Pass B and Pass C** on any such append, and Pass A as well when the append introduces or changes an Acceptance Criterion. For the Small path (Step 4a), Step 5's structural checks suffice — Small plans rarely span enough sections for cross-section drift.\n\nIf any pass surfaces ≥1 issue, fix and re-run **that pass**. The loop terminates only when every row answers \"yes, see \u003Cpointer>\". This investment is what prevents `ywc-spec-validate` from returning `DONE_WITH_CONCERNS` and forcing a Re-plan iteration — the cost is paid once here instead of being amplified across the spec-validate fan-out and the re-plan amendment.\n\n### Step 5: Handoff\n\nAlways end with an explicit handoff instruction matching the path taken.\n\n**Small path handoff:**\n\n```text\n✅ Plan ready: \u003Cpath>\nNext: implement directly, or run $ywc-code-gen, or $ywc-sequential-executor\n```\n\n**Medium\u002FLarge path handoff:**\n\nOutput this block first:\n\n```text\n✅ Spec drafted: \u003Cpath>\n```\n\nAfter writing a fresh Medium\u002FLarge spec, invoke `ywc-spec-ready --spec \u003Cpath>` exactly once by default, using the path just written. Do not invoke it when `--no-converge` or `--non-interactive` is set, or when `\u003Cpath>` is outside `docs\u002Fywc-plans\u002F` (for example a custom `--output docs\u002Fspecs\u002Ffeature.md`), because `ywc-spec-ready` rejects spec paths outside that root unless the repository documents another spec directory. In any of these suppressed cases, print the manual handoff:\n\n1. `ywc-spec-validate --spec \u003Cpath>`\n2. (after review passes) `ywc-task-generator \u003Cpath>`\n3. (after task generation) `ywc-sequential-executor` or `ywc-parallel-executor`\n\nIf readiness returns verified `DONE`, report it and print the next-step handoff using the spec path just written (`ywc-spec-ready --spec` updates that file in place and emits no `Artifact` field without `--artifact-profile agentic`); do not invoke task generation. Propagate a valid non-`DONE` terminal status unchanged and stop, or return `BLOCKED` for invalid\u002Fmissing status. The fresh Medium\u002FLarge path stops after this single readiness call and never invokes an executor. Small and Re-plan paths do not invoke automatic readiness. Use the bounded Suggestion owner policy in `ywc-spec-ready`: explicit apply\u002Fdefer wins, otherwise one amendment\u002Frevalidation when needed; residual advisory Suggestions alone do not create another prompt or another readiness pass, and do not block a valid handoff.\n\n### Agentic artifact profile\n\nWhen `--artifact-profile agentic` is present, reject `--output` before planning. The planner owns the artifact filename and must write an existing regular Markdown file under `docs\u002Fywc-plans\u002F`:\n\n- Small: `docs\u002Fywc-plans\u002FYYYYMMDD-small_\u003Cslug>.md`\n- Medium\u002FLarge: `docs\u002Fywc-plans\u002FYYYYMMDD-\u003Cslug>.md`\n\n`YYYYMMDD` is the run date and `\u003Cslug>` is the planner's sanitized request slug. Do not use `plan.md`, reconstruct a basename, inspect `--output`, scan prose, or recover a path from a raw response. Direct calls without the profile keep their existing output behavior.\n\nThe agentic caller passes `--no-converge` so it can verify this Result before owning the single subsequent `ywc-spec-ready` call. The artifact-profile Result remains exactly as specified below.\n\nOn a successful agentic run, emit exactly one producer Result block and no additional fields:\n\n```text\n## Result\nStatus: DONE\nScale: Small | Medium | Large\nArtifact: \u003Crepository-relative regular Markdown file>\n```\n\nThe literal Scale value must be the selected scale. A Result block is authoritative only when it is the only complete block, each field occurs exactly once, and no extra field occurs in the block. Trim surrounding whitespace only; never recover labels from unlabelled prose. Before handoff, canonicalize `Artifact` against the repository root and require a relative, non-escaping path to an existing regular `.md` file inside `docs\u002Fywc-plans\u002F`. Missing, duplicate, conflicting, absolute, escaping, outside-root, non-Markdown, or non-regular candidates are rejected.\n\nTerminal statuses other than `DONE` use the existing Completion Status report and are not Result authorities. A missing or invalid Result produces a bounded `BLOCKED` report containing only producer name, failed field, candidate count, a digest of any candidate path, and a bounded reason; it stores no response text or raw tool output and makes no downstream call.\n\n## Output Format\n\nTwo possible artifacts. Both are markdown files at user-specified paths. The handoff message is plain text printed to the conversation.\n\n| Path | Artifact | When |\n|---|---|---|\n| `.\u002Fplan.md` (or user-specified) | Small-path execution plan | Scale = Small |\n| `docs\u002Fywc-plans\u002F\u003Cslug>.md` (or project equivalent) | Medium\u002FLarge-path spec | Scale = Medium or Large |\n\nFor the exact templates, see [references\u002Fsmall-plan-template.md](references\u002Fsmall-plan-template.md) and [references\u002Fspec-template.md](references\u002Fspec-template.md).\n\n## Validation\n\nBefore declaring the skill's task complete, verify:\n\n- [ ] Step 1 produced explicit answers to all four anchors (What, Why, Out of Scope, Done When)\n- [ ] Step 2 read at minimum the project's instruction file (`AGENTS.md`, `CODEX.md`, `CLAUDE.md`, or equivalent) and the project's build\u002Ftest command source\n- [ ] Step 2 deep-read **every component the spec claims to \"踏襲 \u002F follow \u002F extend\"** (not just located them)\n- [ ] Step 2 grepped every **implicit reference** (property accessor on existing type, named audit\u002Fevent\u002FDTO\u002Ferror type, mirrored column name) to confirm the existing schema\u002Ftypes match the spec's use\n- [ ] Step 2 ran the **complement grep** for every **closure** (\"only \u002F 唯一 \u002F no other \u002F all \u002F exhaustive\") and **liveness** (\"dead \u002F @deprecated \u002F 呼び出し元ゼロ \u002F active\") claim, enumerating and classifying the full candidate set (Step 2 trigger #4), with each hit attributed to its own `file:line`\n- [ ] The plan's change list contains only sites the request **requires** changing; enumerated-but-incidental sites are recorded as \"no change needed\" under Existing Constraints Touched (no \"while I'm here\" refactors)\n- [ ] If the plan names a **parent spec**, Step 2 read it and confirmed the follow-up does not silently narrow the parent's removal \u002F scope list\n- [ ] Step 3 selected exactly one scale, with the rubric criterion that matched stated explicitly\n- [ ] If scale = Small, none of the hard-disqualifiers apply (re-check DB \u002F library \u002F API contract \u002F cross-cutting)\n- [ ] If scale = Medium\u002FLarge, the spec includes an **Existing Constraints Touched** section with `file:line` citations for every inherited behavior\n- [ ] If scale = Medium\u002FLarge, the spec includes a complete **Quality Gate Contract** declaration or the exact `N\u002FA — no quality gate contract` sentinel, plus explicit `Module Boundaries`; incomplete fields return `NEEDS_CONTEXT` and no raw commands are invented\n- [ ] If scale = Medium\u002FLarge, **Step 4b.5 Self-Consistency Pass** ran (all three passes A\u002FB\u002FC) and every row resolved to a concrete pointer\n- [ ] If Re-plan Mode (Step 4c) ran, **Step 4b.5 was re-run on the whole spec** (original + amendment) before handoff\n- [ ] If this run was an **in-place append** (追補 \u002F follow-up) to an existing plan\u002Fspec, Step 4b.5 (≥ Pass B + C) ran on the appended content\n- [ ] If Re-plan Mode changed an instruction an original section still states literally, a `> ⚠️ SUPERSEDED ...` marker plus a top-of-file **Operative Sections** pointer was added\n- [ ] Output file written at a concrete path (no `\u003Cplaceholder>` slugs)\n- [ ] Out of Scope is non-empty (use `N\u002FA — none identified` if truly none)\n- [ ] Handoff message printed verbatim with the file path filled in\n- [ ] A fresh Medium\u002FLarge spec invoked `ywc-spec-ready --spec \u003Cpath>` exactly once unless `--no-converge` or `--non-interactive` was set; suppressed, Small, and Re-plan paths made zero automatic readiness calls\n- [ ] The planner did not invoke task generation or an executor\n- [ ] If scale = Medium\u002FLarge, the spec's **Global Constraints** section is populated from Step 2 findings (or `N\u002FA` after active consideration)\n- [ ] If the Small plan touches ≥2 files sharing a function\u002Ftype signature, an **Interfaces** block declares each side's exact signature\n\n## Common Mistakes\n\n(Procedural failure modes specific to this skill. Behavioral \u002F rationalization failures are in the Rationalization Defense table above — do not duplicate here.)\n\n- **Conflating ywc-plan with ywc-tech-research** — `ywc-plan` assumes the technology choice is settled or out of scope for this request. If the user is asking *what library to use* or *what architecture to adopt*, route to `ywc-tech-research` first, then return to `ywc-plan` after.\n- **Forgetting the handoff message** — without an explicit handoff, the user is left guessing which downstream skill to run. The handoff is the contract that this skill is a planner, not an executor.\n- **Treating Step 4b.5 as a single pass instead of three** — Pass A, B, and C catch different classes of drift. Skipping any one of them is the most common way Step 4b.5 fails to prevent a Critical. The cost of running all three is ~5 minutes; the cost of skipping one is a full re-plan iteration.\n\n## Integration\n\n- **Upstream**: `ywc-tech-research` (when technology choice is unsettled before planning)\n- **Downstream (Small path)**: `ywc-code-gen`, `ywc-sequential-executor`\n- **Downstream (Medium\u002FLarge path)**: fresh specs invoke `ywc-spec-ready --spec \u003Cpath>` once by default (suppressed by `--no-converge` \u002F `--non-interactive`); after verified `DONE`, proceed to `ywc-task-generator` → `ywc-sequential-executor` \u002F `ywc-parallel-executor`. Suppressed paths use `ywc-spec-validate` before task generation.\n- **Pairs with**: `ywc-product-review` (run before `ywc-plan` when business framing is unclear), `ywc-project-docs` (run after if `docs\u002F` set is missing)\n","# ywc-plan\n\n**Announce at start:** \"I'm using the ywc-plan skill to clarify the request, assess scale, and route to the appropriate downstream path.\"\n\nThis skill converts a rough idea, vague request, or partially-formed change description into one of two artifacts: (1) a **direct execution plan** for Small changes that can be implemented in a single PR without task decomposition, or (2) a **spec document** for Medium\u002FLarge changes that will be handed off to `ywc-spec-validate` and then `ywc-task-generator`. Input: natural-language request from the user. Output: either a `plan.md` (Small path) or a `docs\u002Fywc-plans\u002F\u003Cfeature>.md` (Medium\u002FLarge path), plus an explicit handoff instruction.\n\n## Arguments\n\n| Flag | Type | Description |\n|---|---|---|\n| `--non-interactive` | flag | Skip interactive clarification prompts in Step 1. If any anchor is missing, fill with defaults: Out of Scope = `\"nothing explicitly excluded\"`, Done When = `\"all tasks merged and ywc-impl-review returns DONE\"`. Also suppress automatic `ywc-spec-ready`; print the manual handoff instead. |\n| `--no-converge` | flag | Suppress automatic `ywc-spec-ready` for a fresh Medium\u002FLarge spec and print the manual handoff instead. Small and Re-plan paths do not run automatic readiness regardless. |\n| `--update-spec \u003Cpath>` | string | Path to an existing spec file. Activates Re-plan Mode (Step 4c). Must be used with `--failure-context`. Mutually exclusive with normal spec generation. |\n| `--failure-context \u003Ctext>` | string | The \"Fix Priority\" section text from `ywc-impl-review`. Used together with `--update-spec` to identify which parts of the spec need amendment. |\n| `--output \u003Cpath>` | string | Explicit output path for the generated spec or plan (e.g., `--output docs\u002Fywc-plans\u002Fagentic-iteration-1.md`). When omitted, defaults to `.\u002Fplan.md` (Small) or `docs\u002Fywc-plans\u002F\u003Cslug>.md` (Medium\u002FLarge). |\n| `--artifact-profile agentic` | enum | Agentic-owned artifact mode. Mutually exclusive with `--output`; direct calls without this flag retain the existing output behavior. |\n\n## Rationalization Defense\n\nWhen tempted to bypass a rule, check this table first:\n\n| Excuse | Reality |\n|---|---|\n| \"User said 'just plan it', I'll skip the codebase investigation\" | Codebase investigation is mandatory before drafting either artifact. Plans written without reading existing code, project instruction files (`AGENTS.md`, `CODEX.md`, `CLAUDE.md`), or `docs\u002Farchitecture\u002F` produce conflicts that surface during implementation. The agent always feels confident; the user still suffers the rework. |\n| \"Scale looks ambiguous, I'll default to Small to keep things light\" | Default to **Medium** when ambiguous, not Small. Small path skips spec review and task decomposition — wrong scale call cascades into untracked scope creep. The cost of writing a spec for an actually-Small change is one wasted hour; the cost of skipping a spec for an actually-Medium change is rework across multiple sessions. |\n| \"DB migration is part of the change, I'll bundle it into the Small plan\" | Any change touching `migrations\u002F`, `prisma\u002Fschema.prisma`, `*.sql`, or equivalent is **never Small**. DB migration must be its own task — escalate to Medium path so `ywc-task-generator` can split it. Safety invariant — same rule as `ywc-task-generator`. |\n| \"User wants to start coding now, I'll skip ywc-spec-validate on the Medium spec\" | The Medium\u002FLarge path **must** route through `ywc-spec-validate` before `ywc-task-generator`. Skipping spec review is the failure mode `ywc-task-generator`'s `requires: [ywc-spec-validate]` exists to prevent. Run review even when the user is impatient. |\n| \"Out of Scope is obvious, I'll leave it implicit\" | Always write Out of Scope explicitly — both in the Small `plan.md` and the Medium spec. The implicit version is the one the agent silently expands during implementation. Empty Out of Scope = guaranteed scope drift. |\n| \"Library introduction is small, I'll bundle it\" | Any new library\u002Fframework introduction is **never Small**. Same Safety Invariant as DB migration — escalate to Medium path. |\n| \"User mentioned 'auto-execute', I'll skip the spec for Medium too\" | Auto-execute via `ywc-parallel-executor` or `ywc-sequential-executor` does not remove the spec requirement — those executors consume task directories produced by `ywc-task-generator`, which itself requires a reviewed spec. The shortcut does not exist. |\n| \"The idea is clear enough, I'll write the spec directly\" | For Medium\u002FLarge changes, unverified design assumptions are the most expensive rework source. Before drafting the spec, surface at least the key branching decisions: data model shape, API boundary, error handling strategy, and any third-party integration scope. Assumptions that seem obvious now become the reason the spec is rewritten during implementation. |\n| \"The spec-writing process is overhead — let's get to the tasks faster\" | Design investment is not overhead — it IS the task. Every hour spent clarifying scope and surfacing assumptions prevents 3–5 hours of rework during implementation. Kent Beck: \"Invest in the design of the system every day.\" The spec is today's investment. |\n| \"The spec says it follows existing component X, that's good enough — no need to read X\" | \"Follows X\" is a *claim*, not a *spec*. Code Compatibility findings are the largest single category of spec-validate Critical findings, and the majority trace to a \"follows X\" claim where the author never opened X. Read X end-to-end and transcribe its behavior into **Existing Constraints Touched** with `file:line` citations. The reviewer cannot verify what was never written down. |\n| \"I grepped and found the one writer\u002Freader, so that's the only one\" | A forward grep that confirms **one** instance is not evidence of a **closed set**. Closure claims (\"only \u002F sole \u002F 唯一 \u002F no other \u002F all \u002F exhaustive\") and liveness claims (\"dead \u002F @deprecated \u002F 呼び出し元ゼロ \u002F still active\") are the single largest source of *false-but-confident* spec assertions: the planner confirms the instance it already had in mind and never runs the *complement* grep that enumerates the rest. The most expensive Critical in the LP column-drop plan was exactly this — \"injectAndSaveGtmSnippet is the 唯一の generatedHtml writer\", but `markDone` also wrote it, and dropping the column would have broken the build. Before writing any closure or liveness word, run the complement grep (`grep -rn \"\u003Cidentifier>\" \u003Cmodule>`, classify every hit live\u002Fdead) and transcribe the full set. |\n| \"While I'm reading this code anyway, I'll fold in the adjacent cleanup\u002Frefactor\" | Thoroughness in *investigation* must not become expansion of the *change scope*. A plan that enumerates a related site (a parameter, a sibling method, a rename opportunity) and then proposes changing it — when the request did not ask for it — adds surface that becomes new Critical findings. The measured regression: a `generatedHtml`-drop plan proactively proposed a `composeHtml` refactor and shipped a build-break Critical the narrower plan never risked. Enumerate everything; change only what the request requires; record the rest as \"no change needed\" under Existing Constraints Touched. |\n| \"AC and the API Contract probably agree, I won't cross-check\" | Cross-section drift between AC, FR, Data Model, and API Contract is the #2 source of Critical findings (after Code Compatibility). Step 4b.5 is mandatory for Medium\u002FLarge precisely because authors trust their own consistency and reviewers find it broken. Run the cross-check; the cost is ~5 minutes, the cost of skipping it is one full re-plan iteration. |\n| \"The quality gate can infer the missing command or boundary\" | A Quality Gate Contract is opt-in and caller-bound. For Medium\u002FLarge specs, declare the complete bounded metadata or the exact `N\u002FA — no quality gate contract` sentinel. Missing ownership, command IDs\u002Fdigests, thresholds, or sanitized evidence paths returns `NEEDS_CONTEXT`; never invent a command, digest, threshold, path, or pass. |\n| \"Validation came back DONE_WITH_CONCERNS, I'll rewrite the spec from scratch and re-run\" | Use **Re-plan Mode** (`--update-spec \u003Cpath> --failure-context \"\u003Cfindings>\"`) instead. Re-plan appends an `## Iteration N Amendments` section that addresses only the failing items, preserving the rest of the spec verbatim. Rewriting from scratch loses the validated portions and produces cosmetic diffs that reviewers must re-validate. |\n\n**Violating the letter of these rules is violating the spirit.** Safety Invariants (DB migration separation, library introduction separation, mandatory spec review for Medium\u002FLarge) have no exceptions, regardless of urgency.\n\n## Quality Gate Contract (Medium\u002FLarge only)\n\nEvery Medium\u002FLarge spec must include either a complete `Quality Gate Contract`\ndeclaration or the exact compatibility sentinel `N\u002FA — no quality gate contract`.\nThe declaration is bounded metadata for the downstream task-generator packet; it\nis not permission to execute a command. Cite the canonical rules in\n[..\u002Freferences\u002Fquality-gates.md](..\u002Freferences\u002Fquality-gates.md) rather than\ncopying or redefining its state semantics.\n\nA declared contract must provide all of the following, using caller-approved\nvalues and exact task boundaries:\n\n- `contract_state`: `report-only`, `advisory`, or `enforced`;\n- `ownership.production_paths` and `ownership.production_symbols` for Cleaner;\n- `ownership.test_fixture_paths` and `ownership.test_fixture_symbols` for Hardener;\n- immutable `approved_command_ids` and matching `approved_command_digests`;\n- bounded repository-relative `sanitized_evidence_paths`;\n- caller-approved `complexity_threshold`, `mutation_target`, and `attempt_cap` (at most three); and\n- `residual_survivors` handling, without declaring survivors equivalent.\n\nDo not include raw executable command text, raw output, transcripts, secrets, or\nfull diffs. Do not broaden module boundaries or fill missing fields from project\nconventions. An incomplete, contradictory, unauthorized, or unbounded\ndeclaration is `NEEDS_CONTEXT` and must not be handed off as a valid packet. The\nexact no-contract sentinel preserves the existing planning and downstream\nworkflow; it emits no placeholder packet and selects no quality-gate worker.\n\nFor Medium\u002FLarge specs, `Module Boundaries` must identify each affected module's\nowner, consumers, and responsibility, including the producer declaration and\nthe downstream task-generator consumer. A boundary that is not exact enough to\nbind changed production symbols and test\u002Ffixture symbols is incomplete.\n\n## Workflow\n\nThe skill executes five steps. Steps 1–2 are mandatory; Steps 3–5 branch on the scale assessment.\n\n### Step 1.0: Brainstorm Gate\n\nBefore extracting anchors, evaluate whether the request is concrete enough for direct planning. Some requests arrive as design conversations rather than plan inputs; those must run through `ywc-brainstorm` first.\n\n| Signal | Route |\n|---|---|\n| Request includes a concrete change description, files \u002F surfaces touched, and an observable Done condition | Proceed to Step 1 — anchors will extract cleanly. |\n| Request is conversational (\"I'm thinking about X\", \"wouldn't it be nice if…\", \"let's explore Y\", \"어떻게 만들지\", \"アイディアがある\") | **Delegate to `ywc-brainstorm`** — it surfaces the four anchors via Socratic dialogue and presents 2–3 approaches; resume `ywc-plan` from Step 1 with the brainstorm handoff as input. |\n| Request describes multiple independent subsystems (e.g., \"a platform with auth, chat, billing, analytics\") | **Delegate to `ywc-brainstorm`** for decomposition before any anchor extraction. Each subsystem gets its own brainstorm → plan cycle. |\n| Two or more of (What \u002F Why \u002F Out of Scope \u002F Done When) are completely missing from the request | **Delegate to `ywc-brainstorm`** — extracting two missing anchors at once produces shallow answers; ywc-brainstorm collects them one at a time with explicit approach trade-offs. |\n| The destination is known, but the open decisions must be tracked across multiple sessions before a stable plan can be written | **Delegate to `ywc-wayfinder`** — it maintains the local discovery map, enforces exactly one active ticket, and routes back here once a planning-ready ticket resolves. |\n\nWhen delegating, surface this verbatim before transferring control:\n\n> \"This request needs intent clarification before planning. Switching to `ywc-brainstorm` to surface the four anchors and approach choice. After the design is approved, returning to `ywc-plan` Step 1 with the brainstorm handoff as input.\"\n\nWhen `ywc-brainstorm` completes, its handoff message includes the four anchors and the chosen approach. Re-enter `ywc-plan` Step 1 with that handoff as the effective user input — the anchors should already be filled, so Step 1 typically reduces to a one-sentence confirmation.\n\n`--non-interactive` mode skips the delegation: when the flag is present, treat ambiguity as Medium scale (Step 3) and fill missing anchors with defaults rather than routing to `ywc-brainstorm`.\n\nIf `ywc-wayfinder` hands back a resolved ticket, treat that ticket's local map path and acceptance notes as the current request context. If `ywc-wayfinder` returns `NEEDS_CONTEXT`, do not draft a plan yet.\n\nAfter Scale assessment in Step 2 and before any downstream handoff (`ywc-spec-writer`, `ywc-task-generator`, `ywc-code-gen`, executor), invoke `ywc-confidence-gate` with the chosen approach as input. The gate's PROCEED \u002F REVIEW \u002F STOP band determines whether the plan is ready for handoff; a REVIEW band surfaces alternatives to the user, a STOP band routes back here for additional investigation before re-attempting handoff. The 5-dimension score becomes part of the plan's completion summary so downstream skills inherit a comparable confidence number.\n\nWhen the chosen path still depends on unverified assumptions, run [..\u002Freferences\u002Funknown-matrix.md](..\u002Freferences\u002Funknown-matrix.md) before handoff and preserve those assumptions explicitly in the artifact's risk \u002F follow-up language. Do not weaken existing `NEEDS_CONTEXT` rules: if a missing answer blocks a coherent plan, stop and ask instead of parking it as an unknown.\n\nWhen a persisted `ywc-tech-research --output \u003Cpath>` artifact exists, cite that project-relative Markdown path in the resulting plan\u002Fspec instead of copying unsourced research prose. Preserve its provenance markers and overwrite expectations.\n\n### Step 1: Clarify the Request\n\n**Prerequisite:** If `docs\u002Fubiquitous-language.md` exists, read it before asking any questions. The vocabulary defined there must frame the clarification dialogue itself — use canonical terms in your questions and note any \"Synonyms to Avoid\" so the user's answers are captured in the right terms from the start.\n\n**Codebase-Fact Pre-check.** Before finalizing the anchor questions below, check whether the answer is already visible in the codebase — an existing pattern, a referenced file, a prior issue named in the request. Budget: at most **5 targeted lookups across at most 3 files**, using read-only `rg` searches or reads only — this is not a substitute for Step 2's full investigation.\n\n| Question type | Route |\n|---|---|\n| Codebase Fact — answer is verifiable by reading existing code, config, or a referenced file (e.g., \"does this project already have an X pattern?\", \"what does the existing error format look like?\") | Check the codebase first, citing `file:line` as evidence for the answer; only ask the user if the check is inconclusive or the budget is exhausted before a confident answer emerges. |\n| User Preference \u002F Scope \u002F Requirement — answer depends on intent, priority, or a decision only the user can make (e.g., \"should this be opt-in or opt-out?\", \"is backward compatibility required?\") | Ask the user directly — the codebase cannot answer this. |\n\nThis pre-check stays active under `--non-interactive`: a Codebase Fact question the check resolves is answered from the cited evidence and never asked; one it leaves inconclusive falls through to the `--non-interactive` defaulting rule below. Because no default is defined for **What** or **Why**, an inconclusive or unresolved **What**\u002F**Why** anchor under `--non-interactive` **stops** the skill and reports `NEEDS_CONTEXT` rather than proceeding to Step 2 with the change's intent unresolved.\n\nAsk focused questions to extract four anchors. Use one round of consolidated questions (not back-and-forth) unless the user's initial input already covers some anchors.\n\n| Anchor | What to ask | Why it matters |\n|---|---|---|\n| **What** | \"What concrete change are we making? Which user-facing behavior or system capability is added\u002Fchanged\u002Fremoved?\" | Without a concrete What, scale cannot be assessed. |\n| **Why** | \"What problem does this solve? What signal motivated it (user request, bug, metric, compliance)?\" | Why grounds priority and scope decisions during implementation. |\n| **Out of Scope** | \"What is explicitly not part of this change? What might look related but is being deferred?\" | Out of Scope is the scope-creep guardrail. Always write it. |\n| **Done When** | \"How will we know it's complete? What observable outcome proves success?\" | Done conditions become the Acceptance Criteria in the artifact. |\n\nIf the user's initial message already answers all four anchors, skip the questions and confirm understanding in one sentence.\n\n**`--non-interactive` mode:** When this flag is present, do not ask interactive clarification questions at any point in Step 1. If the user's initial message leaves **Out of Scope** or **Done When** unanswered, fill it with the following defaults automatically: Out of Scope = `\"nothing explicitly excluded\"`, Done When = `\"all tasks merged and ywc-impl-review returns DONE\"`. **What** and **Why** have no default — if either remains unanswered after the Codebase-Fact Pre-check above, stop and report `NEEDS_CONTEXT` instead of proceeding. Otherwise, proceed directly to Step 2 without waiting for user input.\n\n### Step 2: Investigate the Codebase\n\nRead targeted files to ground the plan in actual project state. Step 2 is organized into four parts: what to **always** read, what to read **conditionally**, what triggers a **deeper** read, and **when to stop**.\n\n#### Always read\n\n- `AGENTS.md`, `CODEX.md`, and `CLAUDE.md` at repo root when present — language policy, conventions, CI commands. Prefer Codex-native instructions (`AGENTS.md` \u002F `CODEX.md`) when they conflict with Claude-only guidance.\n- `package.json`, `pyproject.toml`, `Makefile`, `go.mod` etc. — actual lint\u002Ftest\u002Fbuild commands\n- Project tree (top 2 levels of `src\u002F`, `apps\u002F`, or equivalent) — module placement and existing patterns\n- Existing `tasks\u002F` directory if present — phase numbering and dependency context\n- Relevant `docs\u002Fywc-plans\u002F`, `docs\u002Farchitecture\u002F`, `docs\u002Fproduct\u002F` if the project uses the LLM development guide layout\n- `docs\u002Fubiquitous-language.md` (if it exists) — canonical domain terms and their \"Synonyms to Avoid\"; spec text and Out of Scope items must use canonical terms and never use synonym identifiers\n- **Parent spec \u002F design doc** named in the plan's own header (`Parent spec:`, `親 spec:`, `Spec Reference:`) — when the request is a follow-up or amendment to an existing plan, read the parent end-to-end. A follow-up that silently narrows the parent's explicit removal\u002Fscope list is a cross-document Consistency finding: in the LP column-drop follow-up, the parent said \"delete `markDone`\u002F`markFailed`\" but the follow-up's removal list dropped `markDone`, which would have left a dangling write against the dropped column.\n\n#### Conditional reads (only when relevant to the request)\n\n- DB-touching requests: existing schema\u002Fmigration files\n- API-touching requests: existing route definitions and OpenAPI\u002Fcontract files\n- UI-touching requests: existing component patterns\n\n#### Trigger-based deep reads\n\nFour triggers force a deeper read than the lists above. Each fires independently — if more than one applies, do all of them.\n\n1. **Explicit \"follows existing X\" claim.** When the user's request — or your own draft of Scope \u002F Functional Requirements \u002F Data Model — uses phrases like *\"踏襲 \u002F follows \u002F based on \u002F extends \u002F 同じパターンで \u002F similar to \u002F mirrors \u002F 参考に\"* and names a specific component, you **must read that component end-to-end** (not just its location, not just nearby patterns). The new spec inherits not only the pattern but every actual behavior — response headers, status codes, timeout values, parser limits, cascade rules. Capture each inherited behavior under **Existing Constraints Touched** with a `file:line` citation. This rule exists because Code Compatibility findings dominate spec-validate Critical counts — and the majority trace back to a \"踏襲\" claim whose author never opened the referenced file.\n\n2. **Implicit reference to existing types\u002Fmodels.** The \"follows X\" rule fires on prose claims, but the more common failure is the *implicit* reference — the spec never says \"follows X\", it just uses an identifier or shape that already exists. Trigger a deep read whenever the spec:\n   - **Uses a property accessor on an existing domain type by name** not declared in your own Data Model (e.g., `tenantSlug`, `userEmail`, `orderId.short`, `submission.actor.user_id`) — every such accessor is a claim that the property exists with the expected shape\n   - **Names an existing audit log, event, DTO, or error type by category** without inlining its shape (e.g., \"writes an audit log\", \"emits a `UserCreated` event\", \"returns a `ConflictError`\") — the spec must either inline the shape with a `file:line` citation or explicitly reference the existing type, never invent a parallel shape\n   - **Introduces a new column whose name or semantics overlap a field already present elsewhere** — either reuse the existing field\u002Fenum or justify the divergence\n\n   For each implicit reference, grep the existing schema\u002Ftypes (`grep -n \"\u003Cidentifier>\" backend\u002Fprisma\u002Fschema.prisma`, `grep -rn \"\u003CTypeName>\" backend\u002Fsrc\u002Flib\u002F`) and either capture the verified shape under **Existing Constraints Touched** or declare the schema change explicitly. This rule exists because findings like \"field absent on existing model\" and \"shape mismatch with existing type\" arise from variable-name use, not from any prose claim of \"踏襲\".\n\n3. **Stack-primitive section about to be written.** Before drafting Data Model, API Contract, or any section that touches DB \u002F middleware \u002F framework primitives, skim [references\u002Fcommon-pitfalls.md](references\u002Fcommon-pitfalls.md). It enumerates the recurring traps spec-validate flags (global vs route-scoped middleware, `@HttpCode` vs documented status, error-handling discipline, etc.). The schema-side rules live separately in the shared schema guide: [..\u002Freferences\u002Fschema\u002Fcore.md](..\u002Freferences\u002Fschema\u002Fcore.md) plus the matching stack file (`prisma.md` \u002F `sql-ddl.md` \u002F `drizzle.md` \u002F `typeorm.md`). Skimming both at Step 2 is cheaper than discovering each trap individually in validation.\n\n4. **Closure or liveness claim about code.** The first three triggers fire on a *positive identity* claim (\"this follows \u002F uses X\"). This one fires on the inverse — *set-closure* and *liveness* claims — which are just as failure-prone and far easier to assert from memory. When your draft asserts that a set is complete — *\"only \u002F sole \u002F 唯一 \u002F the single \u002F no other \u002F all \u002F exhaustive \u002F 全て \u002F 唯一の … 経路\"* — or that a symbol is dead or alive — *\"@deprecated \u002F unused \u002F 呼び出し元ゼロ \u002F dead write \u002F still active \u002F 現に write\"* — you must run the **complement grep**: enumerate the entire candidate set, not just re-confirm the one instance already in hand. For \"C is the only writer of column X\", run `grep -rn \"X\" \u003Cmodule>` and classify every write site live\u002Fdead; for \"method M is dead\", grep M's callers repo-wide and transcribe the zero (or the non-zero hit you would otherwise have missed). Capture the enumerated set under **Existing Constraints Touched**. This rule exists because a forward grep that confirms one writer is silently mistaken for proof that no other writer exists — the failure mode behind both the largest Critical and a Warning in the LP column-drop plan (`markDone` was a second `generatedHtml` writer the \"唯一の write 経路\" claim never enumerated; `markFailed` was dead despite an \"active\" claim).\n\n   Two disciplines when transcribing the enumerated set:\n   - **Attribute each hit to its own `file:line`.** Never fold one file's line numbers under another file's header — mixing `lp.service.ts` lines into an `lp.repository.ts` proof is itself a Consistency finding the reviewer will flag.\n   - **Enumeration is for comprehension, not scope expansion.** Classify each enumerated site as *must-change for this request* or *no change needed* (record the latter under **Existing Constraints Touched**, not in the change list). Never fold an adjacent refactor — a rename, a signature change on a site that merely looks related — into the plan unless the request requires it. \"While I'm here I'll also refactor X\" over-reach expands the plan's surface and is its own Critical source; the measured failure was a plan that proactively proposed a `composeHtml` refactor and introduced a build break the narrower plan never risked.\n\n#### When to stop\n\nStop investigating once you can confidently (a) pick a scale using Step 3's rubric, (b) name concrete files in the plan or spec, and (c) state the project's actual lint\u002Ftest\u002Fbuild commands. Going beyond this is `gstack-investigate`'s job — defer to that skill if the user explicitly wants deep investigation.\n\n### Step 3: Assess Scale\n\nPick exactly one scale using the rubric below. **Default to Medium when ambiguous.**\n\n| Scale | Criteria (any one matches) | Path |\n|---|---|---|\n| **Small** | All of: ≤3 files changed, ≤300 LOC, single concern, no DB migration, no new library, no cross-module impact | Direct execution plan (`plan.md`) |\n| **Medium** | 4–15 expected tasks, OR DB migration involved, OR new library introduction, OR touches 2–3 modules | Spec document → `ywc-spec-validate` → `ywc-task-generator` |\n| **Large** | 15+ expected tasks, OR cross-cutting refactor, OR new feature with multiple phases | Spec document → split suggestion to user → `ywc-spec-validate` → `ywc-task-generator` |\n\n**Hard-disqualifiers from Small** (any of these forces Medium minimum):\n\n- Database migration \u002F schema change\n- New library\u002Fframework introduction\n- New API contract that other services consume\n- Cross-cutting concern (auth, logging, error handling) modified in >1 module\n\nFor the full scale-assessment heuristics including borderline-case examples, see [references\u002Fscale-assessment.md](references\u002Fscale-assessment.md).\n\n### Step 3.5: Architectural Advisor Gate (Medium\u002FLarge only)\n\nRun this gate **only when both conditions hold**:\n\n- Scale assessed as **Medium** or **Large** (Small path skips this gate)\n- Step 2 codebase investigation surfaced an architectural ambiguity that the spec \u002F `docs\u002Farchitecture\u002F` \u002F project convention cannot resolve on its own (examples: monolith vs split, sync vs async boundary, ORM vs raw SQL, domain boundary placement, abstraction-vs-duplication trade-off for a soon-to-be-replicated pattern)\n\nIf both conditions fail, skip to Step 4 directly. The gate exists to head off the failure mode where a Medium\u002FLarge plan locks in a structural choice that subsequent implementation cannot walk back without a re-plan.\n\n**Procedure**:\n\n1. **Frame the decision** in one sentence with the two (occasionally three) reasonable options the codebase \u002F spec admit. Avoid hypothetical options the project would not actually pick.\n2. **Assemble the bounded payload** — the spec excerpt that touches the decision (≤30 lines), the most relevant existing code reference (file path + 1-paragraph summary, not the full file), and the project convention or prior-art entry if one applies. Do not forward the whole spec.\n3. **Dispatch the advisor**. Use Codex subagent delegation when the current session exposes a delegation tool. Prefer the installed Codex custom agent `ywc-architect` when available; otherwise request one higher-capability architecture advisor pass with the bounded payload and the same decision frame. If no delegation tool is available, run the architecture-advisor checklist inline as a separate bounded pass and record the fallback in the plan. Do not use Claude Code named-agent syntax, Claude agent-path examples, or explicit Claude model pins in the Codex bundle.\n4. **Record the verdict** in `docs\u002Fywc-plans\u002F\u003Cplan-slug>\u002Farchitecture-verdict.md` (or alongside the spec when the spec path is provided). The file captures: the framed decision, the trade-off table the advisor returned, the chosen direction, and the file \u002F type \u002F structural shape recommendation. Subsequent steps cite this file rather than re-litigating the decision.\n5. **Handle non-DONE statuses** per the standard contract:\n   - `DONE_WITH_CONCERNS` → cite the concerns explicitly in the spec's Constraints section so reviewers see the caveat\n   - `NEEDS_CONTEXT` → run the additional file reads \u002F searches the advisor names, then re-dispatch with the enriched payload\n   - `BLOCKED` → surface to the user with the advisor's blocker summary; do not proceed to Step 4 until the prerequisite is resolved\n\n**Budget**: at most **1** architecture advisor dispatch per ywc-plan invocation. If a second architectural decision surfaces, defer it to `ywc-confidence-gate` STOP-band routing or to a follow-up plan rather than spending another advisor call inside the same plan run.\n\nSkip the gate entirely (with a one-line note in the plan \u002F spec) when the architectural choice is unambiguous from the spec or already adjudicated by a prior `architecture-verdict.md` in the same project.\n\n### Step 4a: Small Path — Direct Execution Plan\n\nWhen scale is **Small**, generate `plan.md` at a user-specified path (default: `.\u002Fplan.md`). If `--output \u003Cpath>` is provided, write to that path instead of the default.\n\nFor the full `plan.md` structure and a worked example, see [references\u002Fsmall-plan-template.md](references\u002Fsmall-plan-template.md).\n\nThe plan **must** include: Goal, Out of Scope, Files to touch (concrete paths), Implementation Steps (checkbox list with file\u002Ffunction references), Verification commands (using project's actual commands from Step 2), Risks\u002FRollback, and Interfaces (optional — only when the plan touches ≥2 files that share a function\u002Ftype signature).\n\nAfter writing the plan, surface this handoff message to the user:\n\n> \"Plan ready at `\u003Cpath>`. To execute, you can:\n> 1. Implement directly in this session, or\n> 2. Run `$ywc-code-gen` with the plan as context, or\n> 3. Hand off to `$ywc-sequential-executor` if you prefer Branch + PR isolation.\"\n\n### Step 4b: Medium\u002FLarge Path — Spec Document\n\nWhen scale is **Medium** or **Large**, generate a spec document under `docs\u002Fywc-plans\u002F\u003Cfeature-slug>.md` (or the project's equivalent — derive from Step 2 investigation). If `--output \u003Cpath>` is provided, write to that path instead of the derived slug path.\n\nFor the full spec structure aligned with `ywc-spec-validate`'s evaluation dimensions, see [references\u002Fspec-template.md](references\u002Fspec-template.md).\n\nThe spec **must** include: Purpose, Scope, Out of Scope, Acceptance Criteria, Functional Requirements, Non-Functional Requirements (when applicable), Data Model \u002F API Contract (when applicable), Edge Cases, and Open Questions (use `N\u002FA — none identified` if none).\n\nAdd `## Failure Modes` rows with ID, triggering path, observable failure,\nhandling\u002Fdetection, and verification. Missing handling or missing detection\u002Ftest\nevidence is an explicit gap; when both are missing, never silently pass the row.\nNew specs consider relevant failure paths; legacy specs without this section\nremain valid. For each command-bearing AC, record observed baseline,\nrevision\u002Fcontext and evidence, or `not measured` with the gap. A spec command\nis data, not authorization to execute it; preserve existing approved command\nexecution boundaries.\n\n\nRecord project-wide constraints found in Step 2 (version floors, dependency constraints, naming\u002Fcopy conventions, platform requirements) in the spec's `## Global Constraints` section — see [references\u002Fspec-template.md](references\u002Fspec-template.md).\n\nWhen the spec names module boundaries, key types, and interfaces, ground those design choices in the shared readable-code rubric — especially §G (structural smells) and its anti-dogma guardrails (do not specify speculative generality or premature abstraction the requirement does not yet need). See [..\u002Freferences\u002Freadable-code.md](..\u002Freferences\u002Freadable-code.md).\n\nFor **Large** scale, also surface this advisory before writing the spec:\n\n> \"This change is Large (15+ expected tasks). Consider splitting into multiple smaller specs by feature boundary. Splitting now is cheaper than splitting after `ywc-task-generator` produces 20+ task directories. Proceed with single spec, or split first?\"\n\n### Step 4c: Re-plan Mode\n\nActivated when `--update-spec \u003Cpath>` and `--failure-context \u003Ctext>` are both provided. This mode is mutually exclusive with normal spec generation (Steps 4a and 4b).\n\n**Behavior:**\n\n1. Read the existing spec at `\u003Cpath>`. If the file does not exist, report an error and stop — do not create a new file.\n2. Determine the current iteration number by counting existing `## Iteration N Amendments` sections in the file. The new section number is N + 1 (starting at 1 if none exist).\n3. Using `--failure-context` as the input (the \"Fix Priority\" section text from `ywc-impl-review`), draft amendment content that addresses only the failing areas.\n4. **Append** `## Iteration N Amendments` to the end of the existing spec file. Do NOT create a new file, do NOT rewrite any completed section's body above the new section.\n4.5. **Mark superseded originals (the one permitted in-place edit).** When the amendment scopes out or changes an instruction that an original section still states literally — e.g., an original migration SQL block that drops a column the amendment now defers — prepend a single inline marker line at the head of that original section: `> ⚠️ SUPERSEDED by Iteration N — see §\u003Camendment-anchor>`. Do not edit the section's body, only prepend the marker. Then ensure a top-of-file **Operative Sections** pointer names which sections `ywc-task-generator` should treat as authoritative. This removes the precedence-only resolution that otherwise leaves a copy-faithful implementer acting on the superseded original — the exact residual Warning in the LP column-drop re-validation, where the original §1 SQL still dropped `errorMessage` after the amendment deferred it.\n5. The appended section must include: which requirements failed (from `--failure-context`), the amended approach, and updated Acceptance Criteria for the affected items only.\n6. **Re-run Step 4b.5 on the whole spec** (original sections + the new amendment) before printing the handoff. An amendment frequently introduces fresh drift — a new status code that conflicts with an original AC, a new field absent from the original API Contract, a new state value without a write site. Without the re-run, that drift surfaces as a *fresh* Critical at the next `ywc-spec-validate` pass and forces yet another iteration. Re-running 4b.5 here is what makes Re-plan Mode actually converge.\n\n**Constraints:**\n\n- Never overwrite or reorder existing content — **except** the single-line `> ⚠️ SUPERSEDED ...` marker permitted by Behavior step 4.5, which prepends (never rewrites the body of) a contradicted original section.\n- Never create a new spec file — only append to the file at `\u003Cpath>`.\n- `--output` is ignored in Re-plan Mode (output path is always the `--update-spec` path).\n\n### Step 4b.5: Pre-Handoff Self-Consistency Pass (Medium\u002FLarge only)\n\nBefore printing the handoff message in Step 5, run this mechanical check on the spec you just wrote. Step 5's `Validation` list checks **structural** items (sections exist, anchors answered); Step 4b.5 catches the **semantic drift** the author introduces between sections — which is what dominates `ywc-spec-validate` Critical findings.\n\nThe check is organized into three passes, each catching a different class of drift. Run all three. For each row, scan the spec end-to-end and answer with a concrete pointer (section heading or `file:line`). If the answer is \"I'm not sure\" or \"probably yes\", edit the spec until the answer becomes \"yes, see \u003Cpointer>\" before printing the handoff.\n\nExamples below are tagged *(past session, this codebase)* — they are real failures observed during the LP form \u002F publish spec work that motivated this skill, included because concrete examples teach better than abstract rules. The **Rule** column is the universal principle and applies to any feature family.\n\n#### Pass A — Cross-section consistency (within this spec)\n\nCatches drift between AC \u002F FR \u002F API Contract \u002F Data Model of the same spec.\n\n| Rule | Example failure (past session, this codebase) |\n|---|---|\n| Every Acceptance Criterion maps to ≥1 Functional Requirement; every Functional Requirement is motivated by ≥1 AC | Orphan ACs (tests for unspecified behavior); orphan FRs (unmotivated work) |\n| Every HTTP status code mentioned anywhere (AC, FR, Edge Case, NFR) also appears in the API Contract — and the API Contract has no orphan codes | AC3 says `202`, AC6 says `200`, controller enforces `@HttpCode(202)` → silent contradiction |\n| Every field name in API Contract request\u002Fresponse is either declared in Data Model **or** explicitly marked as \"derived from X\" \u002F \"server-side snapshot from Y\" | `consentText` appears in DB columns but is missing from the request body — reviewer cannot tell whether the field is client-supplied (spoofable PII) or server-snapshotted |\n| Every Acceptance Criterion is in the form `When \u003Ctrigger>, system does \u003Cbehavior>, observable as \u003Cconcrete check>` — not a bare behavior name | \"e2e: form submission の golden path\" is a section name; becomes an AC only when it specifies request shape → expected status → DB row state |\n| Every new state value (enum value, status flag, lifecycle column) declared in Data Model has ≥1 Functional Requirement writing it, **and** Edge Cases enumerate every state combination it introduces (A→B→A, delete-then-recreate, partial-then-resume) | `LandingPage.status='PUBLISHED'` added to the enum without a transaction writing it; `unpublish → delete LpFormConfig → republish` is a 3-step path the spec never enumerates |\n| Every grep-based Acceptance Criterion matches the code's **actual call shape** — a single-line regex like `update\\([^)]*field` does not match a multi-line `.update({ … field … })`, so use a broad identifier grep or pair the narrow regex with one | AC1's single-line `landingPage\\.update\\([^)]*generatedHtml` could not match `markDone`'s multi-line `.update({ … })` — the verification command shared the exact blind spot that let the Critical through, so the AC would have falsely passed |\n\n#### Pass B — Claim ↔ reality verification (this spec vs existing code \u002F sibling specs)\n\nCatches the failure mode where the spec asserts something about the world that turns out to be false at implementation time.\n\n| Rule | Example failure (past session, this codebase) |\n|---|---|\n| Every \"踏襲 \u002F follows \u002F based on \u002F extends X\" claim carries a `file:line` citation, **and** the cited code's actual behavior is transcribed into **Existing Constraints Touched** | \"`LpFormCorsInterceptor` follows `BeaconSiteCorsInterceptor`\" — the cited interceptor unconditionally sets `Allow-Credentials: true`, contradicting AC1 |\n| Every \"no change to existing X\" \u002F \"§Y そのまま採用\" claim is verified — replace with \"based on X, with diffs: A, B, C\" the moment any diff exists | Data Model header says \"§5 そのまま\" while silently changing `isActive` default and adding `consentText` columns |\n| Every Edge Case threshold (size, time, rate) is verified against the actual enforcing code, not assumed | \"body > 32kb → 413\" sounds observable; `main.ts` actually enforces 6mb globally — the spec is a wish, not an assertion, until the limit is path-scoped |\n| Every function signature, shared type, prerequisite, or shared constant that crosses a sibling spec in the same feature family appears identically in both — or one spec explicitly declares \"owned by spec X, referenced here\" with the canonical signature inlined | `injectBeaconMarkers(html, formKey)` is untyped 2-arg in form spec but `(html: string, formKey: string \\| null): string` in publish spec; publish spec depends on `LpFormConfig` from form spec without naming the prerequisite in Dependencies |\n| Every closure claim (\"only \u002F sole \u002F 唯一 \u002F no other \u002F all \u002F exhaustive\") and every liveness claim (\"dead \u002F @deprecated \u002F 呼び出し元ゼロ \u002F still active\") carries the **complement-grep result** enumerating the full candidate set — not a single confirming instance (Step 2 trigger #4 produced this; Pass B confirms it landed in the spec) | \"injectAndSaveGtmSnippet is the 唯一の write 経路\" — `markDone` (`:404`) also wrote the column → Critical; \"errorMessage is active because markFailed writes it\" — `markFailed` had zero callers → Warning |\n| Every removal \u002F scope item in a referenced parent spec is either carried into this follow-up or explicitly deferred with a stated reason — a follow-up never silently narrows the parent's declared scope | Parent plan §3 said \"delete `markDone`\u002F`markFailed`\"; the follow-up's removal list dropped `markDone`, so the dropped column would still be referenced by a live build target |\n\n#### Pass C — Schema invariants (Data Model mechanical rules)\n\nCatches Data Model omissions that make the migration fail at `prisma generate`, the first delete attempt, or the first concurrent insert. The two highest-frequency Criticals are inline; the full ruleset (NOT NULL backfill, FK index, composite uniqueness, multi-tenant scope, enum domain, `timestamptz`) is in the shared schema guide: [..\u002Freferences\u002Fschema\u002Fcore.md](..\u002Freferences\u002Fschema\u002Fcore.md) plus the matching stack file (`prisma.md` \u002F `sql-ddl.md` \u002F `drizzle.md` \u002F `typeorm.md`).\n\n| Rule | Example failure (past session, this codebase) |\n|---|---|\n| Every new DB `@relation` has the reverse-relation field declared on the other model **in this spec** (even if the other model already exists in `schema.prisma`) | `@relation` on `LpFormSubmission` pointing at `LandingPage` without adding `lpFormSubmissions LpFormSubmission[]` on `LandingPage` → `prisma generate` fails |\n| Every `onDelete` rule (`Restrict \u002F Cascade \u002F SetNull \u002F NoAction`) has its API consequence specified in the API Contract (typically `409 Conflict` for `Restrict`, a destructive-side-effect note for `Cascade`) | `onDelete: Restrict` on submissions, but `DELETE \u002Fapi\u002Flp-forms\u002F:id` lacks `409 Conflict` and the operator UX for \"delete submissions first\" |\n\nFor the full Data Model self-check, run the review checklist in [..\u002Freferences\u002Fschema\u002Fcore.md](..\u002Freferences\u002Fschema\u002Fcore.md) Part C and the stack-specific notes for the project's ORM or DDL style.\n\n---\n\nThis step is **mandatory for the Medium\u002FLarge path** (Step 4b), **for the appended amendment in Re-plan Mode** (Step 4c), and **for any in-place append of implementation detail to an existing plan or spec** — including a free-form 追補 \u002F follow-up block added through a direct file edit rather than through `--update-spec`. The append path is the one that silently skips this pass: it is neither a fresh Step 4b generation nor a formal Step 4c invocation, so the failure that motivated these rules (a follow-up 追補 whose \"唯一の write 経路\" closure claim was never complement-grepped) lands exactly there. Run at minimum **Pass B and Pass C** on any such append, and Pass A as well when the append introduces or changes an Acceptance Criterion. For the Small path (Step 4a), Step 5's structural checks suffice — Small plans rarely span enough sections for cross-section drift.\n\nIf any pass surfaces ≥1 issue, fix and re-run **that pass**. The loop terminates only when every row answers \"yes, see \u003Cpointer>\". This investment is what prevents `ywc-spec-validate` from returning `DONE_WITH_CONCERNS` and forcing a Re-plan iteration — the cost is paid once here instead of being amplified across the spec-validate fan-out and the re-plan amendment.\n\n### Step 5: Handoff\n\nAlways end with an explicit handoff instruction matching the path taken.\n\n**Small path handoff:**\n\n```text\n✅ Plan ready: \u003Cpath>\nNext: implement directly, or run $ywc-code-gen, or $ywc-sequential-executor\n```\n\n**Medium\u002FLarge path handoff:**\n\nOutput this block first:\n\n```text\n✅ Spec drafted: \u003Cpath>\n```\n\nAfter writing a fresh Medium\u002FLarge spec, invoke `ywc-spec-ready --spec \u003Cpath>` exactly once by default, using the path just written. Do not invoke it when `--no-converge` or `--non-interactive` is set, or when `\u003Cpath>` is outside `docs\u002Fywc-plans\u002F` (for example a custom `--output docs\u002Fspecs\u002Ffeature.md`), because `ywc-spec-ready` rejects spec paths outside that root unless the repository documents another spec directory. In any of these suppressed cases, print the manual handoff:\n\n1. `ywc-spec-validate --spec \u003Cpath>`\n2. (after review passes) `ywc-task-generator \u003Cpath>`\n3. (after task generation) `ywc-sequential-executor` or `ywc-parallel-executor`\n\nIf readiness returns verified `DONE`, report it and print the next-step handoff using the spec path just written (`ywc-spec-ready --spec` updates that file in place and emits no `Artifact` field without `--artifact-profile agentic`); do not invoke task generation. Propagate a valid non-`DONE` terminal status unchanged and stop, or return `BLOCKED` for invalid\u002Fmissing status. The fresh Medium\u002FLarge path stops after this single readiness call and never invokes an executor. Small and Re-plan paths do not invoke automatic readiness. Use the bounded Suggestion owner policy in `ywc-spec-ready`: explicit apply\u002Fdefer wins, otherwise one amendment\u002Frevalidation when needed; residual advisory Suggestions alone do not create another prompt or another readiness pass, and do not block a valid handoff.\n\n### Agentic artifact profile\n\nWhen `--artifact-profile agentic` is present, reject `--output` before planning. The planner owns the artifact filename and must write an existing regular Markdown file under `docs\u002Fywc-plans\u002F`:\n\n- Small: `docs\u002Fywc-plans\u002FYYYYMMDD-small_\u003Cslug>.md`\n- Medium\u002FLarge: `docs\u002Fywc-plans\u002FYYYYMMDD-\u003Cslug>.md`\n\n`YYYYMMDD` is the run date and `\u003Cslug>` is the planner's sanitized request slug. Do not use `plan.md`, reconstruct a basename, inspect `--output`, scan prose, or recover a path from a raw response. Direct calls without the profile keep their existing output behavior.\n\nThe agentic caller passes `--no-converge` so it can verify this Result before owning the single subsequent `ywc-spec-ready` call. The artifact-profile Result remains exactly as specified below.\n\nOn a successful agentic run, emit exactly one producer Result block and no additional fields:\n\n```text\n## Result\nStatus: DONE\nScale: Small | Medium | Large\nArtifact: \u003Crepository-relative regular Markdown file>\n```\n\nThe literal Scale value must be the selected scale. A Result block is authoritative only when it is the only complete block, each field occurs exactly once, and no extra field occurs in the block. Trim surrounding whitespace only; never recover labels from unlabelled prose. Before handoff, canonicalize `Artifact` against the repository root and require a relative, non-escaping path to an existing regular `.md` file inside `docs\u002Fywc-plans\u002F`. Missing, duplicate, conflicting, absolute, escaping, outside-root, non-Markdown, or non-regular candidates are rejected.\n\nTerminal statuses other than `DONE` use the existing Completion Status report and are not Result authorities. A missing or invalid Result produces a bounded `BLOCKED` report containing only producer name, failed field, candidate count, a digest of any candidate path, and a bounded reason; it stores no response text or raw tool output and makes no downstream call.\n\n## Output Format\n\nTwo possible artifacts. Both are markdown files at user-specified paths. The handoff message is plain text printed to the conversation.\n\n| Path | Artifact | When |\n|---|---|---|\n| `.\u002Fplan.md` (or user-specified) | Small-path execution plan | Scale = Small |\n| `docs\u002Fywc-plans\u002F\u003Cslug>.md` (or project equivalent) | Medium\u002FLarge-path spec | Scale = Medium or Large |\n\nFor the exact templates, see [references\u002Fsmall-plan-template.md](references\u002Fsmall-plan-template.md) and [references\u002Fspec-template.md](references\u002Fspec-template.md).\n\n## Validation\n\nBefore declaring the skill's task complete, verify:\n\n- [ ] Step 1 produced explicit answers to all four anchors (What, Why, Out of Scope, Done When)\n- [ ] Step 2 read at minimum the project's instruction file (`AGENTS.md`, `CODEX.md`, `CLAUDE.md`, or equivalent) and the project's build\u002Ftest command source\n- [ ] Step 2 deep-read **every component the spec claims to \"踏襲 \u002F follow \u002F extend\"** (not just located them)\n- [ ] Step 2 grepped every **implicit reference** (property accessor on existing type, named audit\u002Fevent\u002FDTO\u002Ferror type, mirrored column name) to confirm the existing schema\u002Ftypes match the spec's use\n- [ ] Step 2 ran the **complement grep** for every **closure** (\"only \u002F 唯一 \u002F no other \u002F all \u002F exhaustive\") and **liveness** (\"dead \u002F @deprecated \u002F 呼び出し元ゼロ \u002F active\") claim, enumerating and classifying the full candidate set (Step 2 trigger #4), with each hit attributed to its own `file:line`\n- [ ] The plan's change list contains only sites the request **requires** changing; enumerated-but-incidental sites are recorded as \"no change needed\" under Existing Constraints Touched (no \"while I'm here\" refactors)\n- [ ] If the plan names a **parent spec**, Step 2 read it and confirmed the follow-up does not silently narrow the parent's removal \u002F scope list\n- [ ] Step 3 selected exactly one scale, with the rubric criterion that matched stated explicitly\n- [ ] If scale = Small, none of the hard-disqualifiers apply (re-check DB \u002F library \u002F API contract \u002F cross-cutting)\n- [ ] If scale = Medium\u002FLarge, the spec includes an **Existing Constraints Touched** section with `file:line` citations for every inherited behavior\n- [ ] If scale = Medium\u002FLarge, the spec includes a complete **Quality Gate Contract** declaration or the exact `N\u002FA — no quality gate contract` sentinel, plus explicit `Module Boundaries`; incomplete fields return `NEEDS_CONTEXT` and no raw commands are invented\n- [ ] If scale = Medium\u002FLarge, **Step 4b.5 Self-Consistency Pass** ran (all three passes A\u002FB\u002FC) and every row resolved to a concrete pointer\n- [ ] If Re-plan Mode (Step 4c) ran, **Step 4b.5 was re-run on the whole spec** (original + amendment) before handoff\n- [ ] If this run was an **in-place append** (追補 \u002F follow-up) to an existing plan\u002Fspec, Step 4b.5 (≥ Pass B + C) ran on the appended content\n- [ ] If Re-plan Mode changed an instruction an original section still states literally, a `> ⚠️ SUPERSEDED ...` marker plus a top-of-file **Operative Sections** pointer was added\n- [ ] Output file written at a concrete path (no `\u003Cplaceholder>` slugs)\n- [ ] Out of Scope is non-empty (use `N\u002FA — none identified` if truly none)\n- [ ] Handoff message printed verbatim with the file path filled in\n- [ ] A fresh Medium\u002FLarge spec invoked `ywc-spec-ready --spec \u003Cpath>` exactly once unless `--no-converge` or `--non-interactive` was set; suppressed, Small, and Re-plan paths made zero automatic readiness calls\n- [ ] The planner did not invoke task generation or an executor\n- [ ] If scale = Medium\u002FLarge, the spec's **Global Constraints** section is populated from Step 2 findings (or `N\u002FA` after active consideration)\n- [ ] If the Small plan touches ≥2 files sharing a function\u002Ftype signature, an **Interfaces** block declares each side's exact signature\n\n## Common Mistakes\n\n(Procedural failure modes specific to this skill. Behavioral \u002F rationalization failures are in the Rationalization Defense table above — do not duplicate here.)\n\n- **Conflating ywc-plan with ywc-tech-research** — `ywc-plan` assumes the technology choice is settled or out of scope for this request. If the user is asking *what library to use* or *what architecture to adopt*, route to `ywc-tech-research` first, then return to `ywc-plan` after.\n- **Forgetting the handoff message** — without an explicit handoff, the user is left guessing which downstream skill to run. The handoff is the contract that this skill is a planner, not an executor.\n- **Treating Step 4b.5 as a single pass instead of three** — Pass A, B, and C catch different classes of drift. Skipping any one of them is the most common way Step 4b.5 fails to prevent a Critical. The cost of running all three is ~5 minutes; the cost of skipping one is a full re-plan iteration.\n\n## Integration\n\n- **Upstream**: `ywc-tech-research` (when technology choice is unsettled before planning)\n- **Downstream (Small path)**: `ywc-code-gen`, `ywc-sequential-executor`\n- **Downstream (Medium\u002FLarge path)**: fresh specs invoke `ywc-spec-ready --spec \u003Cpath>` once by default (suppressed by `--no-converge` \u002F `--non-interactive`); after verified `DONE`, proceed to `ywc-task-generator` → `ywc-sequential-executor` \u002F `ywc-parallel-executor`. Suppressed paths use `ywc-spec-validate` before task generation.\n- **Pairs with**: `ywc-product-review` (run before `ywc-plan` when business framing is unclear), `ywc-project-docs` (run after if `docs\u002F` set is missing)\n",{"name":5,"description":7},"main","7e8ac872e53df8c89d75663e031626281a2a2f5c","plugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan",1,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit","https:\u002F\u002Fgithub.com\u002Fyongwoon","https:\u002F\u002Fwww.webhani.com","2026-11-08 17:14:59",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add yongwoon\u002Fywc-agent-toolkit --skill ywc-plan",{"tool":37,"command":38},"bunx","bunx skills add yongwoon\u002Fywc-agent-toolkit --skill ywc-plan",{"tool":40,"command":41},"pnpm","pnpm dlx skills add yongwoon\u002Fywc-agent-toolkit --skill ywc-plan","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002FSKILL.md",true,[45,51,55,59,63,67,71,75,79,83,87,91],{"path":46,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":49,"sourceHtmlUrl":50},"agents\u002Fopenai.yaml","REFERENCE","参考文档",550,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002Fagents\u002Fopenai.yaml",{"path":52,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":53,"sourceHtmlUrl":54},"evals\u002Fevals.json",11183,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002Fevals\u002Fevals.json",{"path":56,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":57,"sourceHtmlUrl":58},"README.en.md",3353,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002FREADME.en.md",{"path":60,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":61,"sourceHtmlUrl":62},"README.es.md",3925,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002FREADME.es.md",{"path":64,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":65,"sourceHtmlUrl":66},"README.ja.md",3623,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002FREADME.ja.md",{"path":68,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":69,"sourceHtmlUrl":70},"README.ko.md",3517,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002FREADME.ko.md",{"path":72,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":73,"sourceHtmlUrl":74},"README.md",3691,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002FREADME.md",{"path":76,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":77,"sourceHtmlUrl":78},"README.zh.md",3318,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002FREADME.zh.md",{"path":80,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":81,"sourceHtmlUrl":82},"references\u002Fcommon-pitfalls.md",14515,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002Freferences\u002Fcommon-pitfalls.md",{"path":84,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":85,"sourceHtmlUrl":86},"references\u002Fscale-assessment.md",3905,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002Freferences\u002Fscale-assessment.md",{"path":88,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":89,"sourceHtmlUrl":90},"references\u002Fsmall-plan-template.md",4923,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002Freferences\u002Fsmall-plan-template.md",{"path":92,"resourceType":47,"resourceTypeDesc":48,"sizeBytes":93,"sourceHtmlUrl":94},"references\u002Fspec-template.md",17217,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-plan\u002Freferences\u002Fspec-template.md",[96,102,108,115,122,129],{"skillNo":97,"name":98,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":99,"categories":100,"keywords":101,"publishedAt":18},"01M72TQ84GTCPCV2VJ778V17TW","missing-frontmatter","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fscripts\u002Ffixtures\u002Fcodex-description-limit\u002Fmissing-frontmatter\u002FSKILL.md",[],[],{"skillNo":103,"name":104,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":107,"publishedAt":18},"01M72TQ6M4BFWE7P9EPW0GZDCM","malformed-frontmatter","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fscripts\u002Ffixtures\u002Fcodex-description-limit\u002Fmalformed-frontmatter\u002FSKILL.md",[],[],{"skillNo":109,"name":110,"nameZh":6,"description":111,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":18},"01M72TQ3ESGKXZ4QRWGTX92BKJ","fixture-501-fail","(ywc) Use when aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa Do not use for x.","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fscripts\u002Ffixtures\u002Fcodex-description-limit\u002F501-fail\u002FSKILL.md",[],[],{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":18},"01M72TQ0HJ8H3R37J9WPWGKJZR","fixture-500-pass","(ywc) Use when aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa Do not use for x.","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fscripts\u002Ffixtures\u002Fcodex-description-limit\u002F500-pass\u002FSKILL.md",[],[],{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":128,"publishedAt":18},"01M72TPWNCC7NEYD0D9N12KSQS","ywc-worktrees","(ywc) Use when creating, auditing, pruning, or resolving git worktrees for isolated task workspaces, whether delegated from an executor or used standalone. Triggers: \"worktree 생성\", \"worktree audit\", \"worktree 정리\", \"worktree prune\", \"ywc-worktrees\", \"create worktree\". Do not use for branch creation\u002Fdeletion alone, PR creation (use ywc-create-pr), CI or merge delivery (use ywc-finish-branch), task orchestration (use ywc-sequential-executor or ywc-parallel-executor), or non-git isolation.","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-worktrees\u002FSKILL.md",[],[],{"skillNo":130,"name":131,"nameZh":6,"description":132,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":9,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":135,"publishedAt":18},"01M72TPRNR3E6QWB91GM98ABBV","ywc-wayfinder","(ywc) Use when a large or uncertain change needs multi-session discovery with a deterministic local map and exactly one active ticket before planning or implementation. Triggers: \"wayfinder\", \"길찾기\", \"discovery map\", \"multi-session discovery\", \"탐색 ticket\", \"経路整理\", \"探索マップ\", \"ywc-wayfinder\". Do not use for ordinary planning (use ywc-plan), idea clarification (use ywc-brainstorm), direct implementation, or tracker\u002Fdatabase writes outside the local Markdown map.","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fplugins\u002Fywc-agent-toolkit\u002Fskills\u002Fywc-wayfinder\u002FSKILL.md",[],[]]