[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M72T7RWY8KA96H4PFEQMSRAB":3,"skill-same:01M72T7RWY8KA96H4PFEQMSRAB":107},{"skillNo":4,"name":5,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":8,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":14,"categories":15,"keywords":16,"publishedAt":17,"linkOnly":18,"markdownContent":19,"markdownBody":20,"frontMatter":21,"refName":22,"commitSha":23,"skillDirectory":24,"forksCount":25,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":28,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M72T7RWY8KA96H4PFEQMSRAB","ywc-spec-writer",null,"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\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002FSKILL.md",[],[],"2026-11-10 22:39:42",false,"---\nname: ywc-spec-writer\nversion: 1.4.0\ndescription: (ywc) Use when creating or updating a project specification (사양서) in docs\u002Fspecification\u002F, including task-range and PR-based incremental updates. Triggers: \"사양서 작성\", \"spec 작성\", \"사양서 업데이트\", \"task 로 사양서 갱신\", \"PR 로 사양서 갱신\", \"write spec\", \"update spec from task range\", \"update spec from PRs\", \"仕様書作成\", \"スペック作成\", \"仕様書更新\", \"タスク範囲から仕様書更新\", \"PRから仕様書更新\", \"编写规范文档\", \"中文规范\", \"escribir especificación\", \"ywc-spec-writer\". Do not use for spec quality review (use ywc-spec-validate), task decomposition from a finalized spec (use ywc-task-generator), or pre-implementation planning without a spec intent (use ywc-plan).\ncategory: spec\nphase: planning\nrequires: []\n---\n\n# ywc-spec-writer\n\n**Announce at start:** \"I'm using the ywc-spec-writer skill to create or update the project specification in docs\u002Fspecification\u002F.\"\n\nWrites and maintains the `docs\u002Fspecification\u002F` directory. Produces human-readable markdown describing the project's goals, features, data model, user flows, and non-functional requirements — with **no program code**. Intended audience: developers and non-developers alike. Supports Korean, Japanese, English, Chinese, and Spanish output.\n\n## Rationalization Defense\n\nWhen tempted to bypass a rule, check this table first:\n\n| Excuse | Reality |\n|---|---|\n| \"This is a minor change — I'll update inline without reading existing spec files\" | Always read existing spec files before writing. Editing without reading overwrites valid content silently. |\n| \"A code snippet would make this feature clearer\" | Zero program code in any spec output. Non-developer audience cannot parse code. Use user stories and flow descriptions instead. |\n| \"User seems to want a full spec — I'll generate it without `--full` to save time\" | Full generation requires the explicit `--full` flag AND user confirmation. Never auto-generate the full spec from an incremental run. |\n| \"The commit changed several files — I'll update the entire spec to be safe\" | Update only sections mapped to the changed domain. Use `scripts\u002Fdetect-affected-sections.sh` to determine scope precisely. |\n| \"Language not specified — I'll default to English\" | Default is Korean (`ko`) unless the project's CLAUDE.md or `--lang` flag says otherwise. |\n| \"`--setup-hook` is optional — I'll just describe the hook approach\" | `--setup-hook` must produce a working script at `tools\u002Fscripts\u002Fspec-update-hook.sh` and install it. Documentation alone does not fulfill the step. |\n| \"Multiple PRs share files — I'll skip deduplication\" | Always dedupe the union file list before invoking section detection. Without dedup, the same diff is fed to the LLM multiple times and bloats context. |\n| \"Open PR diff will change soon — recording the HEAD SHA in README index is unnecessary\" | Always record `headRefOid` (and PR numbers) in the README index entry. Without it, a future reader cannot reproduce or audit which PR snapshot drove the update. |\n| \"The task range or PR set touched >4 sections — I'll patch them all anyway\" | Stop and propose `--update` (Full Refresh) explicitly. Spec changes at that scope are coherent only when written holistically; patching pieces creates internal drift. |\n| \"Range spans phase boundary — I'll silently combine them\" | Phase boundaries are hard gates in `ywc-task-generator`. When a range crosses phases, the README index entry must list every resolved task ID so the audit trail survives. |\n| \"Spec is for business stakeholders, so keeping NFR numbers vague is fine\" | Spec must be **dual-audience**: readable by business stakeholders AND decomposable by `ywc-task-generator`. NFR with placeholder values like \"数秒以内\" \u002F \"X seconds\" fail downstream `ywc-spec-validate` and force a Re-plan iteration. Always extract concrete numbers from `*.constants.ts`, `*config*.ts`, migrations, or record them under Open Questions with rationale. |\n| \"Project has many models — I'll lump them into category groups\" | Every model in `prisma\u002Fschema.prisma` (or equivalent ORM\u002FDB schema) MUST appear by name in `03-data.md`. Lumping ≥3 sibling entities is permitted only as a `### \u003CFamily>` heading with an explicit inline list of all member names. Silent omission produces Code Compatibility Critical findings downstream. |\n| \"Token-efficiency rule says 'no open-ended exploration' — constants files are off-limits\" | The \"no open-ended exploration\" rule has explicit **exceptions** documented in [references\u002Ffull-gen-workflow.md](references\u002Ffull-gen-workflow.md) §Exceptions: constants files, primary schema, feature directory listings, and auth guard \u002F middleware definitions. These supply the concrete numbers and enumeration boundaries that `ywc-spec-validate` checks for. Skipping them produces vague NFRs and lumped entities. |\n| \"UL is for code-level naming, spec uses business language so it's OK\" | `docs\u002Fubiquitous-language.md` is the **canonical vocabulary for the entire project**, not just code. Synonyms-to-Avoid violations (e.g., using \"Tenant Admin\" when UL canonical is \"Admin\" with \"Tenant Admin\" listed as a synonym to avoid) propagate through every downstream artifact: tasks generated by `ywc-task-generator`, code authored by `ywc-backend-coder` \u002F `ywc-frontend-coder`, and PR titles created by `ywc-create-pr`. Skipping the UL cross-check at spec-write time turns a 5-minute grep into a multi-PR rename refactor downstream. Always run the avoid-list extraction grep before drafting `01-overview.md`. |\n| \"Inline backticks are not code blocks, so a Prisma snippet in them is OK\" | Inline backticks containing executable syntax (`@default(...)`, `dbgenerated(...)`, `WHERE x = $1`, decorators) are exactly the case `ywc-spec-validate` flags as a Code Compatibility Warning — the spec then drifts when the underlying ORM \u002F SQL changes. Field-reference identifiers (`tenantId`, `BeaconSite.samplingState`) are fine; **expressions** are not. The mechanical test: \"if I copy this backtick content into a `.prisma` \u002F `.sql` file, would it parse?\" If yes, paraphrase into plain prose. |\n| \"Intent is clear enough — start writing without an up-front scope check\" | Estimating the affected-section count and surfacing any irreversible-choice ambiguity *before* writing prevents a mid-write switch to `--update` and prevents silently deciding an ambiguous design point. Run the Step 1.5 pre-check; record undecided points under `## Open Questions`, never resolve them yourself — a spec writer transcribes decided intent, it does not decide it. |\n\n**Violating the letter of these rules is violating the spirit.** A spec containing code, written in the wrong language, or auto-generated without explicit intent does not serve its readers. A spec that cannot pass `ywc-spec-validate` at the REVIEW band (Gate ≥ 70) does not serve its **pipeline** — fix the gaps at write time, not at validate time.\n\n## Arguments\n\n| Parameter | Format | Example | Description |\n|-----------|--------|---------|-------------|\n| `--full` | flag | `--full` | Generate complete spec from scratch. Requires user confirmation. Uses best available model. |\n| `--update` | flag | `--update` | Regenerate all existing spec sections. |\n| `--from-task` | `--from-task \u003Cpath>` | `--from-task tasks\u002F000002-010-api-user\u002F` | Update spec from a single ywc-task-generator task directory. |\n| `--from-tasks` | `--from-tasks \u003Cid-or-pattern> [\u003Cid-or-pattern> ...]` | `--from-tasks 000002-010..000003-020` | Update spec from a range, glob, or multi-id set of task directories. Patterns: single ID prefix, `START..END` range, shell glob, or multi-value list. Active and completed tasks both resolve. |\n| `--from-commit` | `--from-commit \u003Cref>` | `--from-commit HEAD` | Update spec based on diff of a specific commit. |\n| `--from-pr` | `--from-pr \u003Cnum>` | `--from-pr 42` | Update spec from a single pull request's diff. Requires `gh` CLI auth. |\n| `--from-prs` | `--from-prs \u003Cnum> [\u003Cnum> ...]` | `--from-prs 42 43 51` | Update spec from the union diff of multiple PRs. Each PR fetched via `gh pr diff`; duplicate files are coalesced. |\n| `--setup-hook` | flag | `--setup-hook` | Install git hook for automatic spec-update tracking. |\n| `--lang` | `--lang ko\\|ja\\|en\\|zh\\|es` | `--lang ja` | Output language. Default: `ko`. |\n\n## Workflow\n\n### Step 1: Determine Mode\n\n| Mode | Trigger | Notes |\n|------|---------|-------|\n| **Full Generation** | `--full` | Requires user confirmation. Uses best model. |\n| **Full Refresh** | `--update` | Regenerates all existing sections. |\n| **Task-based Update** | `--from-task \u003Cpath>` | Maps a single task's category to affected sections. |\n| **Task Range Update** | `--from-tasks \u003Cid-or-pattern> ...` | Resolves IDs \u002F ranges \u002F globs via `scripts\u002Fresolve-task-paths.sh`; unions each task's category mapping. |\n| **Commit-based Update** | `--from-commit \u003Cref>` | Analyzes git diff to determine affected sections. |\n| **PR-based Update** | `--from-pr \u003Cnum>` \u002F `--from-prs \u003Cnum> ...` | Fetches changed files via `scripts\u002Fcollect-files-from-prs.sh` (gh CLI); unions across PRs; uses PR title + body as narrative context. |\n| **Auto** | No flags | Reads last commit diff; runs commit-based update. |\n\n### Step 1.5: Scope & Intent Pre-Check\n\nBefore collecting context and writing, right-size the run and confirm intent. This is the \"Right Job, Right Tool\" gate for spec writing — it surfaces the routing decision up front instead of discovering it mid-write.\n\n- **Estimate scope early.** For incremental modes, roughly estimate the affected-section count from the task\u002FPR\u002Fcommit before doing the precise detection in Step 5. If it is likely to exceed the Step 5 safety threshold (>4 sections), propose `--update` (Full Refresh) now rather than after partial writing. For `--full` \u002F `--update`, note the project's entity and feature scale so the per-section size cap (see Step 6) is applied from the start.\n- **Confirm intent on irreversible choices.** If the source (task \u002F PR \u002F commit \u002F design note) admits two readings that change the spec's meaning — especially on an irreversible choice (data ownership, sync vs. async boundary, API versioning) — surface it as one clarifying question OR record both readings under `## Open Questions`. Never silently pick one; the spec writer transcribes decided intent, it does not decide it.\n\n### Step 2: Collect Context\n\n**Always read before writing:**\n- `docs\u002Fspecification\u002FREADME.md` — current spec state (if exists)\n- `CLAUDE.md` — language policy, domain conventions\n- `docs\u002Fubiquitous-language.md` (if exists) — canonical terms; use these verbatim in spec text\n\n**For `--full` and `--update` only**, also read:\n- Project directory structure (top 2 levels of `src\u002F`, `app\u002F`, or equivalent)\n- `docs\u002Fywc-plans\u002F` — existing feature plans\n- Key structural files: schema, API route index, main domain directories\n\n### Step 3: Language Setup\n\nIf `--lang` is not specified, resolve the output language via the shared resolution reference.\n\n> Run `bash \"${CLAUDE_SKILL_DIR}\u002F..\u002Fscripts\u002Fresolve-language.sh\" [--lang \u003Ccode>]`.\n> Resolved code → use it directly. `UNRESOLVED` → fall through to this skill's own fallback below.\n\nThis skill's terminal fallback is unchanged (AC10): when no canonical `## Language Policy` is configured, honor a project CLAUDE.md's declared primary documentation language if present, otherwise default to Korean (`ko`). Ask the user only when they explicitly ask to choose a language or the project guidance conflicts.\n\n> \"사양서를 어떤 언어로 작성할까요? \u002F Which language should the spec be written in? \u002F 仕様書をどの言語で作成しますか？\"\n> 1. 한국어 (ko) — 기본값\n> 2. English (en)\n> 3. 日本語 (ja)\n> 4. 中文 (zh)\n> 5. Español (es)\n\nWhen asking, wait for the user's answer before proceeding.\n\nFor locale-specific writing rules (formality level, term policy), see [references\u002Flanguage-policy.md](references\u002Flanguage-policy.md).\n\n### Step 4: Prepare Spec Directory\n\nIf `docs\u002Fspecification\u002F` does not exist, run:\n\n```bash\nbash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Finit-spec-structure.sh\" \u003Clang> \"\u003CProjectName>\"\n```\n\nPass the language code **resolved in Step 3** as the `\u003Clang>` first positional argument so the scaffolded skeleton is created in the resolved language, not just the document bodies (Amendment A4). This creates the 7-section skeleton without any LLM calls. For the full section layout and writing templates, see [references\u002Fspec-structure.md](references\u002Fspec-structure.md).\n\n### Step 5: Determine Affected Sections\n\nFor incremental modes, identify which spec sections need updating before writing. Run the appropriate branch then **union** every detected section across sources.\n\n**Commit-based**\n\n```bash\ngit diff \u003Cref>^..\u003Cref> --name-only \\\n  | bash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fdetect-affected-sections.sh\"\n```\n\n**Task-based (single task)** — read the task `README.md` for its `category` field and apply the mapping in [references\u002Fsection-mapping.md](references\u002Fsection-mapping.md).\n\n**Task Range \u002F Multi-task** — resolve task IDs, then read each task's `README.md` for its `category` field:\n\n```bash\n# Resolve range \u002F glob \u002F multi-id to absolute task directory paths\nbash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fresolve-task-paths.sh\" \\\n  000002-010..000003-020\n\n# For each resolved path: read README.md → category → look up in section-mapping.md\n# Then UNION every resulting section list.\n```\n\n**PR-based (single or multiple PRs)** — fetch the changed-file union, then feed it into `detect-affected-sections.sh`:\n\n```bash\nbash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fcollect-files-from-prs.sh\" 42 43 51 \\\n  | bash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fdetect-affected-sections.sh\"\n```\n\nAdditionally, for `--from-pr` \u002F `--from-prs`, fetch each PR's title + body as narrative context:\n\n```bash\ngh pr view \u003Cnum> --json number,title,body,headRefOid\n```\n\nUse the PR's `title` + `body` to inform spec wording (the \"why\") and record `headRefOid` in the README change log entry for reproducibility.\n\n**Safety threshold** — if the unioned section count exceeds **4**, stop and propose `--update` (Full Refresh) to the user. Patching that many sections piecemeal produces internal drift; see [references\u002Fsection-mapping.md](references\u002Fsection-mapping.md) §\"When Many Sections Are Affected\".\n\n### Step 6: Write or Update Spec Content\n\n**Non-negotiable writing rules for all modes:**\n- Zero program code in any spec output\n- When the source (task \u002F PR \u002F commit \u002F design note) admits two readings that change the spec's meaning, record **both** under `## Open Questions` rather than silently picking one. A spec writer transcribes decided intent; it does not decide it. The silent pick is invisible until implementation contradicts the spec.\n- Write for a **dual audience**: business stakeholder (must be readable without engineering knowledge) AND `ywc-task-generator` (must be decomposable into concrete tasks). Vague prose serves neither — concrete numbers serve both.\n- Features use the user story format: \"As a [user], I want [action] so that [benefit]\"\n- Data and flows use plain-language descriptions\n- Section file size cap, scaled to project size:\n  - Default: ≤ 400 lines per section file\n  - When project has **>50 entities** (Prisma models \u002F equivalent ORM models) OR **>20 features** (top-level feature directories): cap raises to ≤ 800 lines per section file\n  - `03-data.md` may exceed the section cap by up to 30 lines per entity beyond 50 entities (e.g., 82 entities → cap = 400 + 30×32 = 1,360 lines), so enumeration is not artificially blocked by the cap\n\n**Additional non-negotiable rules for `--full` and `--update` modes** (these modes claim to produce a complete spec, so they bear the full burden):\n\n- Every NFR in `06-requirements.md` MUST include ≥1 quantitative target (latency, throughput, retention period, concurrency, etc.). If the project does not yet have a target, list it under an `## Open Questions` section with the reason, do NOT leave it as a placeholder like \"X seconds\" or vague prose like \"数秒以内\".\n- Every model in the project's primary schema (`prisma\u002Fschema.prisma`, `*\u002Fmigrations\u002F*.sql`, `*\u002Fmodels\u002F`, or `*\u002Fentities\u002F`) MUST appear by name in `03-data.md`. Sibling entities sharing a prefix MAY be grouped under one `### \u003CFamily>` heading, but each member name MUST appear in the inline list under that heading.\n- When the project has **≥3 distinct actor roles** (Operator\u002FAdmin\u002FOwner\u002Fetc.), `02-features.md` or `06-requirements.md` MUST include a Role × Action matrix.\n- When the project has **long-lived high-volume data** (audit logs, time-series analytics, event streams), `06-requirements.md` MUST include a Data Lifecycle subsection covering retention period per entity, sampling strategy, and aggregation timing.\n- Constants and config files (`*.constants.ts`, `*config*.ts`, `*.config.json`, `**\u002Fconfig\u002F*.yaml`) MUST be referenced in spec under \"Existing Constraints Touched\" or an equivalent subsection. The concrete numbers in these files (plan limits, retry counts, retention periods, fee rates, timeouts) are the source of truth for the NFR section.\n- **Ubiquitous Language cross-check**: When `docs\u002Fubiquitous-language.md` exists, extract its `Synonyms to Avoid` column (see one-liner in [references\u002Ffull-gen-workflow.md](references\u002Ffull-gen-workflow.md) §Exceptions) **before drafting `01-overview.md`**. Every role \u002F entity \u002F domain concept name introduced anywhere in the spec MUST be **absent** from that avoid-list. Names found in the avoid-list MUST either:\n  - be **replaced with the canonical term** from the same UL row (e.g., \"Tenant Admin\" → restructure as \"Operator (Billing scope)\" if Operator is the canonical), or\n  - be **proposed as a new canonical term in `§Open Questions`** for the next UL update (e.g., add row \"Tenant Owner\" if a third tier truly exists beyond Operator + Admin).\n  Silently introducing avoid-list synonyms is the most common Consistency Warning at `ywc-spec-validate` time, and it propagates to every downstream artifact (tasks, code, PR titles) — fix at write time, not at validate time.\n- **No ORM \u002F SQL \u002F schema syntax in any section** — the \"no code\" rule applies cross-section, not only to `03-data.md`. Even **inline backtick mentions** of Prisma directives (`@default`, `@relation`, `@@index`, `dbgenerated(...)`), SQL fragments (`SELECT`, `WHERE`, `CREATE TABLE`), or ORM-specific configuration (TypeORM decorators, SQLAlchemy column definitions) count as code and MUST be paraphrased into plain language. Examples:\n  - ✗ `tenantId String @default(dbgenerated(\"current_setting('app.tenant_id'::text)\"))` を設定\n  - ✓ `tenantId` 列に PostgreSQL session variable `app.tenant_id` の現在値を default として bind し、RLS で他テナント行を遮断\n  - ✗ `WHERE tenant_id = $1 AND status = 'ACTIVE'`\n  - ✓ クエリは tenant ID と active status の 2 条件で絞り込む\n  Identifier names (e.g., `tenantId`, `BeaconSite.samplingState`) in inline backticks are permitted because they are field references, not syntax — the test is \"would this paste into `schema.prisma` \u002F `*.sql` \u002F decorator code and execute?\". If yes, paraphrase.\n\nFor per-section writing templates, see [references\u002Fspec-structure.md](references\u002Fspec-structure.md).\n\nFor **Full Generation**, follow the detailed analysis steps in [references\u002Ffull-gen-workflow.md](references\u002Ffull-gen-workflow.md). Use **claude-opus-4-8** or the best available model.\n\n### Step 7: Update README Index\n\nAfter every write, update `docs\u002Fspecification\u002FREADME.md`:\n- Set `**Last updated**` to today's date\n- Append a row in this format: `| YYYY-MM-DD | \u003Csection(s)> | \u003Csource> | \u003Cone-line summary> |`\n\nThe `\u003Csource>` column captures provenance so future readers can trace the spec change back to its driver:\n\n| Mode | `\u003Csource>` example |\n|------|--------------------|\n| Full Generation \u002F Refresh | `--full` or `--update` |\n| Commit-based | `commit \u003Cshort-sha>` |\n| Task-based (single) | `task 000002-010-api-user` |\n| Task Range \u002F Multi | `tasks 000002-010..000003-020 (3 tasks)` — list every resolved ID inline or in a sub-bullet when >5 |\n| PR-based (single) | `PR #42 @ \u003CheadRefOid-short>` |\n| PR-based (multi) | `PRs #42, #43, #51 @ \u003CheadRefOid-short each>` |\n\n### Step 8: Hook Setup (if `--setup-hook`)\n\nSee [references\u002Fhook-setup.md](references\u002Fhook-setup.md) for the full installation procedure. The hook creates a `.spec-update-pending` marker on commits with significant code changes, keeping Claude API calls out of the git hook itself.\n\n## Output Format\n\n```text\n✅ Spec updated: docs\u002Fspecification\u002F\n  Modified: 02-features.md, 03-data.md\n  Unchanged: 01-overview.md, 04-interfaces.md, 05-user-flows.md, 06-requirements.md, 07-glossary.md\n  Index updated: docs\u002Fspecification\u002FREADME.md\n```\n\nFor Task Range \u002F Multi:\n\n```text\n✅ Spec updated: docs\u002Fspecification\u002F\n  Source: tasks 000002-010..000003-020 (4 tasks)\n    - 000002-010-api-user\n    - 000002-020-api-auth\n    - 000003-010-domain-billing\n    - 000003-020-domain-invoice\n  Modified: 02-features.md, 03-data.md, 04-interfaces.md\n  Index updated: docs\u002Fspecification\u002FREADME.md\n```\n\nFor PR-based (single or multi):\n\n```text\n✅ Spec updated: docs\u002Fspecification\u002F\n  Source: PRs #42 @ a1b2c3d, #43 @ e4f5g6h\n  Modified: 02-features.md, 04-interfaces.md\n  Index updated: docs\u002Fspecification\u002FREADME.md\n```\n\nFor Full Generation \u002F Full Refresh:\n\n```text\n✅ Spec generated: docs\u002Fspecification\u002F\n  Created: README.md, 01-overview.md, 02-features.md, 03-data.md,\n           04-interfaces.md, 05-user-flows.md, 06-requirements.md, 07-glossary.md\n  Model: claude-opus-4-8\n  Language: Korean (ko)\n```\n\n## Validation\n\nBefore declaring the skill's task complete:\n\n- [ ] Zero program code in any generated spec file\n- [ ] Language matches `--lang` option or default `ko`\n- [ ] For incremental modes: only affected sections updated\n- [ ] `docs\u002Fspecification\u002FREADME.md` change log updated with today's date\n- [ ] Change log row includes the `\u003Csource>` column (mode + identifier per Step 7 table)\n- [ ] For Task Range \u002F Multi: every resolved task ID is listed (inline or sub-bullet)\n- [ ] For PR-based: every PR number and its `headRefOid` short SHA recorded\n- [ ] If unioned affected sections > 4: user explicitly confirmed continuing with incremental update instead of switching to `--update`\n- [ ] All written sections have substantive content (no \"To be written\" placeholder remaining)\n- [ ] Technical terms kept in English per language policy (not transliterated)\n\n**Pipeline alignment (for `--full` \u002F `--update` only)** — the next pipeline stage is `ywc-spec-validate`, so the writer must self-check against the validator's rubric before declaring done:\n\n- [ ] Every NFR in `06-requirements.md` has ≥1 quantitative target (no `X seconds` \u002F `Y users` placeholders, no vague prose like \"数秒以内\")\n- [ ] Every model in the project's primary schema appears by name in `03-data.md` (lumping permitted only as `### \u003CFamily>` heading with explicit inline member list)\n- [ ] Role × Action matrix exists in `02-features.md` or `06-requirements.md` when the project has ≥3 actor roles\n- [ ] Data Lifecycle subsection exists in `06-requirements.md` when the project has audit \u002F analytics \u002F time-series data\n- [ ] Constants files (`*.constants.ts`, `*config*.ts`, etc.) referenced under \"Existing Constraints Touched\" or an equivalent subsection with `file:line`-style citation\n- [ ] **Ubiquitous Language cross-check passed** — when `docs\u002Fubiquitous-language.md` exists, every role \u002F entity \u002F concept name in the spec was verified **absent** from the `Synonyms to Avoid` column via the grep one-liner in `references\u002Ffull-gen-workflow.md` §Exceptions. Any found synonym was either replaced with the canonical term OR proposed as a new canonical term in `§Open Questions`. (Skip when UL doc absent.)\n- [ ] **No ORM \u002F SQL \u002F schema syntax leak** — every section (not only `03-data.md`) verified free of Prisma directives (`@default`, `@relation`, `@@index`, `dbgenerated(...)`), SQL fragments (`SELECT`, `WHERE`, `CREATE TABLE`, etc.), and ORM-specific decorator \u002F column-definition syntax. Inline backticks containing such syntax MUST be paraphrased into plain prose. Field-reference identifiers (`tenantId`, `BeaconSite.samplingState`) remain permitted.\n- [ ] Spec is expected to pass `ywc-spec-validate` at Gate ≥ 70 (REVIEW band) for downstream hand-off; `--full` mode aims for Gate ≥ 90 (PROCEED band)\n\n## Common Mistakes\n\n- **Reading nothing before writing** — always read existing spec and CLAUDE.md first to avoid overwriting valid content or misusing domain terminology.\n- **Including code in spec output** — even a one-line variable name breaks non-developer readability. Replace with flow descriptions or plain-language attribute lists.\n- **Running full generation without `--full`** — unexpected long-running model calls surprise users. The explicit flag is the contract.\n- **Skipping PR HEAD SHA capture** — for `--from-pr` \u002F `--from-prs`, an open PR's diff can shift the next day. Without `headRefOid` in the change log, the spec update becomes un-reproducible.\n- **Silently merging cross-phase task ranges** — when `--from-tasks` spans a phase boundary, list every resolved task ID in the change log. Combining them without enumeration hides the boundary crossing from audit.\n- **Forgetting PR narrative context** — `gh pr diff` alone gives mechanical file changes; the PR title and body carry the \"why\". Spec writing without the narrative produces description-of-what instead of statement-of-intent text.\n\n## Integration\n\n- **Upstream**: `ywc-plan` (generates feature specs), `ywc-task-generator` (produces task docs for `--from-task` \u002F `--from-tasks`), `ywc-create-pr` (produces PR artifacts consumed by `--from-pr` \u002F `--from-prs`)\n- **Downstream**: `ywc-spec-validate` (validates the written spec before task decomposition)\n- **Pairs with**: `ywc-ubiquitous-language` (align spec vocabulary with canonical domain terms)\n- **External dependency**: `gh` CLI must be installed and authenticated for `--from-pr` \u002F `--from-prs`\n","# ywc-spec-writer\n\n**Announce at start:** \"I'm using the ywc-spec-writer skill to create or update the project specification in docs\u002Fspecification\u002F.\"\n\nWrites and maintains the `docs\u002Fspecification\u002F` directory. Produces human-readable markdown describing the project's goals, features, data model, user flows, and non-functional requirements — with **no program code**. Intended audience: developers and non-developers alike. Supports Korean, Japanese, English, Chinese, and Spanish output.\n\n## Rationalization Defense\n\nWhen tempted to bypass a rule, check this table first:\n\n| Excuse | Reality |\n|---|---|\n| \"This is a minor change — I'll update inline without reading existing spec files\" | Always read existing spec files before writing. Editing without reading overwrites valid content silently. |\n| \"A code snippet would make this feature clearer\" | Zero program code in any spec output. Non-developer audience cannot parse code. Use user stories and flow descriptions instead. |\n| \"User seems to want a full spec — I'll generate it without `--full` to save time\" | Full generation requires the explicit `--full` flag AND user confirmation. Never auto-generate the full spec from an incremental run. |\n| \"The commit changed several files — I'll update the entire spec to be safe\" | Update only sections mapped to the changed domain. Use `scripts\u002Fdetect-affected-sections.sh` to determine scope precisely. |\n| \"Language not specified — I'll default to English\" | Default is Korean (`ko`) unless the project's CLAUDE.md or `--lang` flag says otherwise. |\n| \"`--setup-hook` is optional — I'll just describe the hook approach\" | `--setup-hook` must produce a working script at `tools\u002Fscripts\u002Fspec-update-hook.sh` and install it. Documentation alone does not fulfill the step. |\n| \"Multiple PRs share files — I'll skip deduplication\" | Always dedupe the union file list before invoking section detection. Without dedup, the same diff is fed to the LLM multiple times and bloats context. |\n| \"Open PR diff will change soon — recording the HEAD SHA in README index is unnecessary\" | Always record `headRefOid` (and PR numbers) in the README index entry. Without it, a future reader cannot reproduce or audit which PR snapshot drove the update. |\n| \"The task range or PR set touched >4 sections — I'll patch them all anyway\" | Stop and propose `--update` (Full Refresh) explicitly. Spec changes at that scope are coherent only when written holistically; patching pieces creates internal drift. |\n| \"Range spans phase boundary — I'll silently combine them\" | Phase boundaries are hard gates in `ywc-task-generator`. When a range crosses phases, the README index entry must list every resolved task ID so the audit trail survives. |\n| \"Spec is for business stakeholders, so keeping NFR numbers vague is fine\" | Spec must be **dual-audience**: readable by business stakeholders AND decomposable by `ywc-task-generator`. NFR with placeholder values like \"数秒以内\" \u002F \"X seconds\" fail downstream `ywc-spec-validate` and force a Re-plan iteration. Always extract concrete numbers from `*.constants.ts`, `*config*.ts`, migrations, or record them under Open Questions with rationale. |\n| \"Project has many models — I'll lump them into category groups\" | Every model in `prisma\u002Fschema.prisma` (or equivalent ORM\u002FDB schema) MUST appear by name in `03-data.md`. Lumping ≥3 sibling entities is permitted only as a `### \u003CFamily>` heading with an explicit inline list of all member names. Silent omission produces Code Compatibility Critical findings downstream. |\n| \"Token-efficiency rule says 'no open-ended exploration' — constants files are off-limits\" | The \"no open-ended exploration\" rule has explicit **exceptions** documented in [references\u002Ffull-gen-workflow.md](references\u002Ffull-gen-workflow.md) §Exceptions: constants files, primary schema, feature directory listings, and auth guard \u002F middleware definitions. These supply the concrete numbers and enumeration boundaries that `ywc-spec-validate` checks for. Skipping them produces vague NFRs and lumped entities. |\n| \"UL is for code-level naming, spec uses business language so it's OK\" | `docs\u002Fubiquitous-language.md` is the **canonical vocabulary for the entire project**, not just code. Synonyms-to-Avoid violations (e.g., using \"Tenant Admin\" when UL canonical is \"Admin\" with \"Tenant Admin\" listed as a synonym to avoid) propagate through every downstream artifact: tasks generated by `ywc-task-generator`, code authored by `ywc-backend-coder` \u002F `ywc-frontend-coder`, and PR titles created by `ywc-create-pr`. Skipping the UL cross-check at spec-write time turns a 5-minute grep into a multi-PR rename refactor downstream. Always run the avoid-list extraction grep before drafting `01-overview.md`. |\n| \"Inline backticks are not code blocks, so a Prisma snippet in them is OK\" | Inline backticks containing executable syntax (`@default(...)`, `dbgenerated(...)`, `WHERE x = $1`, decorators) are exactly the case `ywc-spec-validate` flags as a Code Compatibility Warning — the spec then drifts when the underlying ORM \u002F SQL changes. Field-reference identifiers (`tenantId`, `BeaconSite.samplingState`) are fine; **expressions** are not. The mechanical test: \"if I copy this backtick content into a `.prisma` \u002F `.sql` file, would it parse?\" If yes, paraphrase into plain prose. |\n| \"Intent is clear enough — start writing without an up-front scope check\" | Estimating the affected-section count and surfacing any irreversible-choice ambiguity *before* writing prevents a mid-write switch to `--update` and prevents silently deciding an ambiguous design point. Run the Step 1.5 pre-check; record undecided points under `## Open Questions`, never resolve them yourself — a spec writer transcribes decided intent, it does not decide it. |\n\n**Violating the letter of these rules is violating the spirit.** A spec containing code, written in the wrong language, or auto-generated without explicit intent does not serve its readers. A spec that cannot pass `ywc-spec-validate` at the REVIEW band (Gate ≥ 70) does not serve its **pipeline** — fix the gaps at write time, not at validate time.\n\n## Arguments\n\n| Parameter | Format | Example | Description |\n|-----------|--------|---------|-------------|\n| `--full` | flag | `--full` | Generate complete spec from scratch. Requires user confirmation. Uses best available model. |\n| `--update` | flag | `--update` | Regenerate all existing spec sections. |\n| `--from-task` | `--from-task \u003Cpath>` | `--from-task tasks\u002F000002-010-api-user\u002F` | Update spec from a single ywc-task-generator task directory. |\n| `--from-tasks` | `--from-tasks \u003Cid-or-pattern> [\u003Cid-or-pattern> ...]` | `--from-tasks 000002-010..000003-020` | Update spec from a range, glob, or multi-id set of task directories. Patterns: single ID prefix, `START..END` range, shell glob, or multi-value list. Active and completed tasks both resolve. |\n| `--from-commit` | `--from-commit \u003Cref>` | `--from-commit HEAD` | Update spec based on diff of a specific commit. |\n| `--from-pr` | `--from-pr \u003Cnum>` | `--from-pr 42` | Update spec from a single pull request's diff. Requires `gh` CLI auth. |\n| `--from-prs` | `--from-prs \u003Cnum> [\u003Cnum> ...]` | `--from-prs 42 43 51` | Update spec from the union diff of multiple PRs. Each PR fetched via `gh pr diff`; duplicate files are coalesced. |\n| `--setup-hook` | flag | `--setup-hook` | Install git hook for automatic spec-update tracking. |\n| `--lang` | `--lang ko\\|ja\\|en\\|zh\\|es` | `--lang ja` | Output language. Default: `ko`. |\n\n## Workflow\n\n### Step 1: Determine Mode\n\n| Mode | Trigger | Notes |\n|------|---------|-------|\n| **Full Generation** | `--full` | Requires user confirmation. Uses best model. |\n| **Full Refresh** | `--update` | Regenerates all existing sections. |\n| **Task-based Update** | `--from-task \u003Cpath>` | Maps a single task's category to affected sections. |\n| **Task Range Update** | `--from-tasks \u003Cid-or-pattern> ...` | Resolves IDs \u002F ranges \u002F globs via `scripts\u002Fresolve-task-paths.sh`; unions each task's category mapping. |\n| **Commit-based Update** | `--from-commit \u003Cref>` | Analyzes git diff to determine affected sections. |\n| **PR-based Update** | `--from-pr \u003Cnum>` \u002F `--from-prs \u003Cnum> ...` | Fetches changed files via `scripts\u002Fcollect-files-from-prs.sh` (gh CLI); unions across PRs; uses PR title + body as narrative context. |\n| **Auto** | No flags | Reads last commit diff; runs commit-based update. |\n\n### Step 1.5: Scope & Intent Pre-Check\n\nBefore collecting context and writing, right-size the run and confirm intent. This is the \"Right Job, Right Tool\" gate for spec writing — it surfaces the routing decision up front instead of discovering it mid-write.\n\n- **Estimate scope early.** For incremental modes, roughly estimate the affected-section count from the task\u002FPR\u002Fcommit before doing the precise detection in Step 5. If it is likely to exceed the Step 5 safety threshold (>4 sections), propose `--update` (Full Refresh) now rather than after partial writing. For `--full` \u002F `--update`, note the project's entity and feature scale so the per-section size cap (see Step 6) is applied from the start.\n- **Confirm intent on irreversible choices.** If the source (task \u002F PR \u002F commit \u002F design note) admits two readings that change the spec's meaning — especially on an irreversible choice (data ownership, sync vs. async boundary, API versioning) — surface it as one clarifying question OR record both readings under `## Open Questions`. Never silently pick one; the spec writer transcribes decided intent, it does not decide it.\n\n### Step 2: Collect Context\n\n**Always read before writing:**\n- `docs\u002Fspecification\u002FREADME.md` — current spec state (if exists)\n- `CLAUDE.md` — language policy, domain conventions\n- `docs\u002Fubiquitous-language.md` (if exists) — canonical terms; use these verbatim in spec text\n\n**For `--full` and `--update` only**, also read:\n- Project directory structure (top 2 levels of `src\u002F`, `app\u002F`, or equivalent)\n- `docs\u002Fywc-plans\u002F` — existing feature plans\n- Key structural files: schema, API route index, main domain directories\n\n### Step 3: Language Setup\n\nIf `--lang` is not specified, resolve the output language via the shared resolution reference.\n\n> Run `bash \"${CLAUDE_SKILL_DIR}\u002F..\u002Fscripts\u002Fresolve-language.sh\" [--lang \u003Ccode>]`.\n> Resolved code → use it directly. `UNRESOLVED` → fall through to this skill's own fallback below.\n\nThis skill's terminal fallback is unchanged (AC10): when no canonical `## Language Policy` is configured, honor a project CLAUDE.md's declared primary documentation language if present, otherwise default to Korean (`ko`). Ask the user only when they explicitly ask to choose a language or the project guidance conflicts.\n\n> \"사양서를 어떤 언어로 작성할까요? \u002F Which language should the spec be written in? \u002F 仕様書をどの言語で作成しますか？\"\n> 1. 한국어 (ko) — 기본값\n> 2. English (en)\n> 3. 日本語 (ja)\n> 4. 中文 (zh)\n> 5. Español (es)\n\nWhen asking, wait for the user's answer before proceeding.\n\nFor locale-specific writing rules (formality level, term policy), see [references\u002Flanguage-policy.md](references\u002Flanguage-policy.md).\n\n### Step 4: Prepare Spec Directory\n\nIf `docs\u002Fspecification\u002F` does not exist, run:\n\n```bash\nbash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Finit-spec-structure.sh\" \u003Clang> \"\u003CProjectName>\"\n```\n\nPass the language code **resolved in Step 3** as the `\u003Clang>` first positional argument so the scaffolded skeleton is created in the resolved language, not just the document bodies (Amendment A4). This creates the 7-section skeleton without any LLM calls. For the full section layout and writing templates, see [references\u002Fspec-structure.md](references\u002Fspec-structure.md).\n\n### Step 5: Determine Affected Sections\n\nFor incremental modes, identify which spec sections need updating before writing. Run the appropriate branch then **union** every detected section across sources.\n\n**Commit-based**\n\n```bash\ngit diff \u003Cref>^..\u003Cref> --name-only \\\n  | bash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fdetect-affected-sections.sh\"\n```\n\n**Task-based (single task)** — read the task `README.md` for its `category` field and apply the mapping in [references\u002Fsection-mapping.md](references\u002Fsection-mapping.md).\n\n**Task Range \u002F Multi-task** — resolve task IDs, then read each task's `README.md` for its `category` field:\n\n```bash\n# Resolve range \u002F glob \u002F multi-id to absolute task directory paths\nbash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fresolve-task-paths.sh\" \\\n  000002-010..000003-020\n\n# For each resolved path: read README.md → category → look up in section-mapping.md\n# Then UNION every resulting section list.\n```\n\n**PR-based (single or multiple PRs)** — fetch the changed-file union, then feed it into `detect-affected-sections.sh`:\n\n```bash\nbash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fcollect-files-from-prs.sh\" 42 43 51 \\\n  | bash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fdetect-affected-sections.sh\"\n```\n\nAdditionally, for `--from-pr` \u002F `--from-prs`, fetch each PR's title + body as narrative context:\n\n```bash\ngh pr view \u003Cnum> --json number,title,body,headRefOid\n```\n\nUse the PR's `title` + `body` to inform spec wording (the \"why\") and record `headRefOid` in the README change log entry for reproducibility.\n\n**Safety threshold** — if the unioned section count exceeds **4**, stop and propose `--update` (Full Refresh) to the user. Patching that many sections piecemeal produces internal drift; see [references\u002Fsection-mapping.md](references\u002Fsection-mapping.md) §\"When Many Sections Are Affected\".\n\n### Step 6: Write or Update Spec Content\n\n**Non-negotiable writing rules for all modes:**\n- Zero program code in any spec output\n- When the source (task \u002F PR \u002F commit \u002F design note) admits two readings that change the spec's meaning, record **both** under `## Open Questions` rather than silently picking one. A spec writer transcribes decided intent; it does not decide it. The silent pick is invisible until implementation contradicts the spec.\n- Write for a **dual audience**: business stakeholder (must be readable without engineering knowledge) AND `ywc-task-generator` (must be decomposable into concrete tasks). Vague prose serves neither — concrete numbers serve both.\n- Features use the user story format: \"As a [user], I want [action] so that [benefit]\"\n- Data and flows use plain-language descriptions\n- Section file size cap, scaled to project size:\n  - Default: ≤ 400 lines per section file\n  - When project has **>50 entities** (Prisma models \u002F equivalent ORM models) OR **>20 features** (top-level feature directories): cap raises to ≤ 800 lines per section file\n  - `03-data.md` may exceed the section cap by up to 30 lines per entity beyond 50 entities (e.g., 82 entities → cap = 400 + 30×32 = 1,360 lines), so enumeration is not artificially blocked by the cap\n\n**Additional non-negotiable rules for `--full` and `--update` modes** (these modes claim to produce a complete spec, so they bear the full burden):\n\n- Every NFR in `06-requirements.md` MUST include ≥1 quantitative target (latency, throughput, retention period, concurrency, etc.). If the project does not yet have a target, list it under an `## Open Questions` section with the reason, do NOT leave it as a placeholder like \"X seconds\" or vague prose like \"数秒以内\".\n- Every model in the project's primary schema (`prisma\u002Fschema.prisma`, `*\u002Fmigrations\u002F*.sql`, `*\u002Fmodels\u002F`, or `*\u002Fentities\u002F`) MUST appear by name in `03-data.md`. Sibling entities sharing a prefix MAY be grouped under one `### \u003CFamily>` heading, but each member name MUST appear in the inline list under that heading.\n- When the project has **≥3 distinct actor roles** (Operator\u002FAdmin\u002FOwner\u002Fetc.), `02-features.md` or `06-requirements.md` MUST include a Role × Action matrix.\n- When the project has **long-lived high-volume data** (audit logs, time-series analytics, event streams), `06-requirements.md` MUST include a Data Lifecycle subsection covering retention period per entity, sampling strategy, and aggregation timing.\n- Constants and config files (`*.constants.ts`, `*config*.ts`, `*.config.json`, `**\u002Fconfig\u002F*.yaml`) MUST be referenced in spec under \"Existing Constraints Touched\" or an equivalent subsection. The concrete numbers in these files (plan limits, retry counts, retention periods, fee rates, timeouts) are the source of truth for the NFR section.\n- **Ubiquitous Language cross-check**: When `docs\u002Fubiquitous-language.md` exists, extract its `Synonyms to Avoid` column (see one-liner in [references\u002Ffull-gen-workflow.md](references\u002Ffull-gen-workflow.md) §Exceptions) **before drafting `01-overview.md`**. Every role \u002F entity \u002F domain concept name introduced anywhere in the spec MUST be **absent** from that avoid-list. Names found in the avoid-list MUST either:\n  - be **replaced with the canonical term** from the same UL row (e.g., \"Tenant Admin\" → restructure as \"Operator (Billing scope)\" if Operator is the canonical), or\n  - be **proposed as a new canonical term in `§Open Questions`** for the next UL update (e.g., add row \"Tenant Owner\" if a third tier truly exists beyond Operator + Admin).\n  Silently introducing avoid-list synonyms is the most common Consistency Warning at `ywc-spec-validate` time, and it propagates to every downstream artifact (tasks, code, PR titles) — fix at write time, not at validate time.\n- **No ORM \u002F SQL \u002F schema syntax in any section** — the \"no code\" rule applies cross-section, not only to `03-data.md`. Even **inline backtick mentions** of Prisma directives (`@default`, `@relation`, `@@index`, `dbgenerated(...)`), SQL fragments (`SELECT`, `WHERE`, `CREATE TABLE`), or ORM-specific configuration (TypeORM decorators, SQLAlchemy column definitions) count as code and MUST be paraphrased into plain language. Examples:\n  - ✗ `tenantId String @default(dbgenerated(\"current_setting('app.tenant_id'::text)\"))` を設定\n  - ✓ `tenantId` 列に PostgreSQL session variable `app.tenant_id` の現在値を default として bind し、RLS で他テナント行を遮断\n  - ✗ `WHERE tenant_id = $1 AND status = 'ACTIVE'`\n  - ✓ クエリは tenant ID と active status の 2 条件で絞り込む\n  Identifier names (e.g., `tenantId`, `BeaconSite.samplingState`) in inline backticks are permitted because they are field references, not syntax — the test is \"would this paste into `schema.prisma` \u002F `*.sql` \u002F decorator code and execute?\". If yes, paraphrase.\n\nFor per-section writing templates, see [references\u002Fspec-structure.md](references\u002Fspec-structure.md).\n\nFor **Full Generation**, follow the detailed analysis steps in [references\u002Ffull-gen-workflow.md](references\u002Ffull-gen-workflow.md). Use **claude-opus-4-8** or the best available model.\n\n### Step 7: Update README Index\n\nAfter every write, update `docs\u002Fspecification\u002FREADME.md`:\n- Set `**Last updated**` to today's date\n- Append a row in this format: `| YYYY-MM-DD | \u003Csection(s)> | \u003Csource> | \u003Cone-line summary> |`\n\nThe `\u003Csource>` column captures provenance so future readers can trace the spec change back to its driver:\n\n| Mode | `\u003Csource>` example |\n|------|--------------------|\n| Full Generation \u002F Refresh | `--full` or `--update` |\n| Commit-based | `commit \u003Cshort-sha>` |\n| Task-based (single) | `task 000002-010-api-user` |\n| Task Range \u002F Multi | `tasks 000002-010..000003-020 (3 tasks)` — list every resolved ID inline or in a sub-bullet when >5 |\n| PR-based (single) | `PR #42 @ \u003CheadRefOid-short>` |\n| PR-based (multi) | `PRs #42, #43, #51 @ \u003CheadRefOid-short each>` |\n\n### Step 8: Hook Setup (if `--setup-hook`)\n\nSee [references\u002Fhook-setup.md](references\u002Fhook-setup.md) for the full installation procedure. The hook creates a `.spec-update-pending` marker on commits with significant code changes, keeping Claude API calls out of the git hook itself.\n\n## Output Format\n\n```text\n✅ Spec updated: docs\u002Fspecification\u002F\n  Modified: 02-features.md, 03-data.md\n  Unchanged: 01-overview.md, 04-interfaces.md, 05-user-flows.md, 06-requirements.md, 07-glossary.md\n  Index updated: docs\u002Fspecification\u002FREADME.md\n```\n\nFor Task Range \u002F Multi:\n\n```text\n✅ Spec updated: docs\u002Fspecification\u002F\n  Source: tasks 000002-010..000003-020 (4 tasks)\n    - 000002-010-api-user\n    - 000002-020-api-auth\n    - 000003-010-domain-billing\n    - 000003-020-domain-invoice\n  Modified: 02-features.md, 03-data.md, 04-interfaces.md\n  Index updated: docs\u002Fspecification\u002FREADME.md\n```\n\nFor PR-based (single or multi):\n\n```text\n✅ Spec updated: docs\u002Fspecification\u002F\n  Source: PRs #42 @ a1b2c3d, #43 @ e4f5g6h\n  Modified: 02-features.md, 04-interfaces.md\n  Index updated: docs\u002Fspecification\u002FREADME.md\n```\n\nFor Full Generation \u002F Full Refresh:\n\n```text\n✅ Spec generated: docs\u002Fspecification\u002F\n  Created: README.md, 01-overview.md, 02-features.md, 03-data.md,\n           04-interfaces.md, 05-user-flows.md, 06-requirements.md, 07-glossary.md\n  Model: claude-opus-4-8\n  Language: Korean (ko)\n```\n\n## Validation\n\nBefore declaring the skill's task complete:\n\n- [ ] Zero program code in any generated spec file\n- [ ] Language matches `--lang` option or default `ko`\n- [ ] For incremental modes: only affected sections updated\n- [ ] `docs\u002Fspecification\u002FREADME.md` change log updated with today's date\n- [ ] Change log row includes the `\u003Csource>` column (mode + identifier per Step 7 table)\n- [ ] For Task Range \u002F Multi: every resolved task ID is listed (inline or sub-bullet)\n- [ ] For PR-based: every PR number and its `headRefOid` short SHA recorded\n- [ ] If unioned affected sections > 4: user explicitly confirmed continuing with incremental update instead of switching to `--update`\n- [ ] All written sections have substantive content (no \"To be written\" placeholder remaining)\n- [ ] Technical terms kept in English per language policy (not transliterated)\n\n**Pipeline alignment (for `--full` \u002F `--update` only)** — the next pipeline stage is `ywc-spec-validate`, so the writer must self-check against the validator's rubric before declaring done:\n\n- [ ] Every NFR in `06-requirements.md` has ≥1 quantitative target (no `X seconds` \u002F `Y users` placeholders, no vague prose like \"数秒以内\")\n- [ ] Every model in the project's primary schema appears by name in `03-data.md` (lumping permitted only as `### \u003CFamily>` heading with explicit inline member list)\n- [ ] Role × Action matrix exists in `02-features.md` or `06-requirements.md` when the project has ≥3 actor roles\n- [ ] Data Lifecycle subsection exists in `06-requirements.md` when the project has audit \u002F analytics \u002F time-series data\n- [ ] Constants files (`*.constants.ts`, `*config*.ts`, etc.) referenced under \"Existing Constraints Touched\" or an equivalent subsection with `file:line`-style citation\n- [ ] **Ubiquitous Language cross-check passed** — when `docs\u002Fubiquitous-language.md` exists, every role \u002F entity \u002F concept name in the spec was verified **absent** from the `Synonyms to Avoid` column via the grep one-liner in `references\u002Ffull-gen-workflow.md` §Exceptions. Any found synonym was either replaced with the canonical term OR proposed as a new canonical term in `§Open Questions`. (Skip when UL doc absent.)\n- [ ] **No ORM \u002F SQL \u002F schema syntax leak** — every section (not only `03-data.md`) verified free of Prisma directives (`@default`, `@relation`, `@@index`, `dbgenerated(...)`), SQL fragments (`SELECT`, `WHERE`, `CREATE TABLE`, etc.), and ORM-specific decorator \u002F column-definition syntax. Inline backticks containing such syntax MUST be paraphrased into plain prose. Field-reference identifiers (`tenantId`, `BeaconSite.samplingState`) remain permitted.\n- [ ] Spec is expected to pass `ywc-spec-validate` at Gate ≥ 70 (REVIEW band) for downstream hand-off; `--full` mode aims for Gate ≥ 90 (PROCEED band)\n\n## Common Mistakes\n\n- **Reading nothing before writing** — always read existing spec and CLAUDE.md first to avoid overwriting valid content or misusing domain terminology.\n- **Including code in spec output** — even a one-line variable name breaks non-developer readability. Replace with flow descriptions or plain-language attribute lists.\n- **Running full generation without `--full`** — unexpected long-running model calls surprise users. The explicit flag is the contract.\n- **Skipping PR HEAD SHA capture** — for `--from-pr` \u002F `--from-prs`, an open PR's diff can shift the next day. Without `headRefOid` in the change log, the spec update becomes un-reproducible.\n- **Silently merging cross-phase task ranges** — when `--from-tasks` spans a phase boundary, list every resolved task ID in the change log. Combining them without enumeration hides the boundary crossing from audit.\n- **Forgetting PR narrative context** — `gh pr diff` alone gives mechanical file changes; the PR title and body carry the \"why\". Spec writing without the narrative produces description-of-what instead of statement-of-intent text.\n\n## Integration\n\n- **Upstream**: `ywc-plan` (generates feature specs), `ywc-task-generator` (produces task docs for `--from-task` \u002F `--from-tasks`), `ywc-create-pr` (produces PR artifacts consumed by `--from-pr` \u002F `--from-prs`)\n- **Downstream**: `ywc-spec-validate` (validates the written spec before task decomposition)\n- **Pairs with**: `ywc-ubiquitous-language` (align spec vocabulary with canonical domain terms)\n- **External dependency**: `gh` CLI must be installed and authenticated for `--from-pr` \u002F `--from-prs`\n",{},"main","7e8ac872e53df8c89d75663e031626281a2a2f5c","claude-code\u002Fskills\u002Fywc-spec-writer",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":7,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add yongwoon\u002Fywc-agent-toolkit --skill ywc-spec-writer",{"tool":36,"command":37},"bunx","bunx skills add yongwoon\u002Fywc-agent-toolkit --skill ywc-spec-writer",{"tool":39,"command":40},"pnpm","pnpm dlx skills add yongwoon\u002Fywc-agent-toolkit --skill ywc-spec-writer","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002FSKILL.md",true,[44,50,54,58,62,65,69,73,77,81,85,89,95,99,103],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"README.en.md","REFERENCE","参考文档",3887,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002FREADME.en.md",{"path":51,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":52,"sourceHtmlUrl":53},"README.es.md",3839,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002FREADME.es.md",{"path":55,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":56,"sourceHtmlUrl":57},"README.ja.md",4178,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002FREADME.ja.md",{"path":59,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":60,"sourceHtmlUrl":61},"README.ko.md",4092,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002FREADME.ko.md",{"path":63,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":60,"sourceHtmlUrl":64},"README.md","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002FREADME.md",{"path":66,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":67,"sourceHtmlUrl":68},"README.zh.md",3257,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002FREADME.zh.md",{"path":70,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":71,"sourceHtmlUrl":72},"references\u002Ffull-gen-workflow.md",6267,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002Freferences\u002Ffull-gen-workflow.md",{"path":74,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":75,"sourceHtmlUrl":76},"references\u002Fhook-setup.md",2289,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002Freferences\u002Fhook-setup.md",{"path":78,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":79,"sourceHtmlUrl":80},"references\u002Flanguage-policy.md",2730,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002Freferences\u002Flanguage-policy.md",{"path":82,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":83,"sourceHtmlUrl":84},"references\u002Fsection-mapping.md",1844,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002Freferences\u002Fsection-mapping.md",{"path":86,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":87,"sourceHtmlUrl":88},"references\u002Fspec-structure.md",6793,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002Freferences\u002Fspec-structure.md",{"path":90,"resourceType":91,"resourceTypeDesc":92,"sizeBytes":93,"sourceHtmlUrl":94},"scripts\u002Fcollect-files-from-prs.sh","SCRIPT","脚本",1772,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002Fscripts\u002Fcollect-files-from-prs.sh",{"path":96,"resourceType":91,"resourceTypeDesc":92,"sizeBytes":97,"sourceHtmlUrl":98},"scripts\u002Fdetect-affected-sections.sh",2028,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002Fscripts\u002Fdetect-affected-sections.sh",{"path":100,"resourceType":91,"resourceTypeDesc":92,"sizeBytes":101,"sourceHtmlUrl":102},"scripts\u002Finit-spec-structure.sh",1436,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002Fscripts\u002Finit-spec-structure.sh",{"path":104,"resourceType":91,"resourceTypeDesc":92,"sizeBytes":105,"sourceHtmlUrl":106},"scripts\u002Fresolve-task-paths.sh",5342,"https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fclaude-code\u002Fskills\u002Fywc-spec-writer\u002Fscripts\u002Fresolve-task-paths.sh",[108,114,120,127,134,141],{"skillNo":109,"name":110,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":8,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":17},"01M72TQ84GTCPCV2VJ778V17TW","missing-frontmatter","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fscripts\u002Ffixtures\u002Fcodex-description-limit\u002Fmissing-frontmatter\u002FSKILL.md",[],[],{"skillNo":115,"name":116,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":8,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":117,"categories":118,"keywords":119,"publishedAt":17},"01M72TQ6M4BFWE7P9EPW0GZDCM","malformed-frontmatter","https:\u002F\u002Fgithub.com\u002Fyongwoon\u002Fywc-agent-toolkit\u002Fblob\u002Fmain\u002Fscripts\u002Ffixtures\u002Fcodex-description-limit\u002Fmalformed-frontmatter\u002FSKILL.md",[],[],{"skillNo":121,"name":122,"nameZh":6,"description":123,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":8,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":124,"categories":125,"keywords":126,"publishedAt":17},"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":128,"name":129,"nameZh":6,"description":130,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":8,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":131,"categories":132,"keywords":133,"publishedAt":17},"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":135,"name":136,"nameZh":6,"description":137,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":8,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":138,"categories":139,"keywords":140,"publishedAt":17},"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":142,"name":143,"nameZh":6,"description":144,"descriptionZh":6,"repositoryFullName":7,"ownerLogin":8,"ownerAvatarUrl":9,"ownerAccountNo":10,"ownerDisplayName":8,"repositoryNo":11,"starsCount":12,"licenseSpdxId":13,"licenseFileUrl":6,"sourceHtmlUrl":145,"categories":146,"keywords":147,"publishedAt":17},"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",[],[]]