[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6JPB918JSPR993BFX34DXSA":3,"skill-same:01M6JPB918JSPR993BFX34DXSA":97},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":31,"publishedAt":52,"linkOnly":53,"markdownContent":54,"markdownBody":55,"frontMatter":56,"refName":58,"commitSha":59,"skillDirectory":60,"forksCount":14,"repositoryHtmlUrl":61,"repositoryHomepageUrl":6,"ownerHtmlUrl":62,"ownerBlogUrl":6,"ownerDescription":63,"updatedAt":64,"install":65,"resources":78},"01M6JPB918JSPR993BFX34DXSA","project-documentation",null,"Write project docs — README, contributing guides, API docs, changelogs, inline docs — and reconcile existing docs after a change made them wrong. Owns doc drift from the change in front of you; a repo-wide doc-rot audit belongs to technical-debt-review; how the project is run (process, tracking, session routines) → working-agreement.","SWEStash\u002Fswe-workflow-skills","SWEStash","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F272895713?v=4","01M6JNRQ84JN5WFK9S1V5H4G46","SWE Stash","01M6JNRQCM45X8WPNHY30TSAB0",1,"MIT","https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fdevops\u002Fskills\u002Fproject-documentation\u002FSKILL.md",[18,23,26],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51],"project documentation","documentation","project","reconcile","inline","you","guides","inline docs","write a readme","drift","technical-debt","review","write","how","api","audit","contributing","changelog","run","change","2026-11-10 10:12:30",false,"---\nname: project-documentation\ndescription: \"Write project docs — README, contributing guides, API docs, changelogs, inline docs — and reconcile existing docs after a change made them wrong. Owns doc drift from the change in front of you; a repo-wide doc-rot audit belongs to technical-debt-review; how the project is run (process, tracking, session routines) → working-agreement.\"\nwhen_to_use: \"Triggers: write a README, document this project, contributing guide, changelog, API docs, this needs docs, docstrings, do the docs still match, are the docs still accurate, doc sweep, stale docs, doc drift, I renamed X — what else needs updating.\"\n---\n\n# Project Documentation\n\nHelp create and maintain documentation that makes a project understandable, usable, and contributable. Good documentation answers three questions: What is this? How do I use it? How do I contribute?\n\n## Document Types\n\nIdentify which documents the project needs based on context:\n\n| Document | When Needed | Audience |\n|----------|-------------|----------|\n| README.md | Every project | Users, contributors, evaluators |\n| CONTRIBUTING.md | Open source or team > 3 | New contributors |\n| API Documentation | Any project with an API | API consumers |\n| CHANGELOG.md | Any project with releases | Users upgrading between versions |\n| Architecture docs | Complex systems | New team members, future maintainers |\n| Inline docs (JSDoc\u002Fdocstrings) | Public APIs, complex logic | Developers reading the code |\n\nAsk the user which they need. If unsure, start with README — every project needs one.\nEvery document must answer a question someone actually has, so for each new one\nyou propose or are asked for, **ask the user who reads it and what question it\nanswers for them**, next to your draft or plan rather than in place of it.\n\nTwo modes use this skill. **Authoring** creates a document that doesn't exist yet\n(the four workflows below). **Sync** reconciles documents that already exist\nbecause a change made them wrong — that's the next section, and it's the mode you\nwant when someone says \"I changed X\" rather than \"write me a Y\".\n\n## The Documentation Strategy — What Ships and What Doesn't\n\nEstablish once with the user: **which artifacts are git-versioned, and which stay\ninternal.** Most projects accumulate both, and only one of them is readable by\nsomeone who has the repo and nothing else.\n\n| Typically versioned | Typically internal |\n|---|---|\n| README, contributing guide, API docs, changelog | Execution plans and phase breakdowns |\n| ADRs and architecture docs | Findings\u002Fbug logs kept during a work session |\n| Roadmaps the project chooses to publish | Scratchpads, handoff prompts, session notes |\n| Runbooks and operational docs | Anything under a gitignored directory |\n\nThis boundary is not bureaucracy — it decides what vocabulary the project's own\nartifacts are allowed to use. **A term is usable in a versioned file only if a\nversioned file defines it.** When a plan lives outside the repo, its phases,\ncheckpoints, and task codes name a conversation, and a reader hitting `Phase 2` or\n`CP1.3` in a comment or commit has nothing to resolve it against. Write what the\nterm means instead.\n\nThe reverse also holds and matters just as much: when a project *does* ship its\nplan or roadmap, referencing it is good practice, not a leak. Check which case\nyou're in rather than assuming either — `git ls-files` answers it.\n\n**On a greenfield project** nothing is tracked yet, so this is a decision to make,\nnot a fact to look up.\n\n**Exit condition** — one line, then write the document in the same response:\n*\"Nothing is tracked yet, so `\u003Cterm>` resolves to nothing for a reader; I've\nwritten the meaning instead. Worth deciding whether the plan itself ships.\"*\n\n**This is not a gate on authoring.** Raise the boundary, apply the safe default —\nmeanings rather than labels, which is never wrong and costs nothing to change — and\ndeliver the document. Never answer a request for docs with the boundary question\nalone: the user asked for a README, and a README that avoids unresolvable\nvocabulary is strictly better than a question. Ask when the answer would change\nwhat you write; otherwise state the assumption and write.\n\n`verification-before-completion`'s publish gate reads this boundary as its baseline\nwhen checking a staged diff.\n\n## Workflow: Sync After a Change\n\nDocs don't rot evenly. They rot where a change moved something a document names,\nand nobody reread that document. Work from the diff, not from a general sense\nthat the docs feel old:\n\n1. **Derive the identifiers.** From the diff, list what a reader could be relying\n   on: flags, env vars, config keys, endpoints, commands, script names, package\n   and directory names, install\u002Fsetup steps, public exported symbols. Include the\n   **old** names — those are what the docs still say.\n2. **Grep the doc set** for each: README, `docs\u002F`, and inline docs.\n3. **Triage each hit** — wrong (contradicts the code now), incomplete (the code\n   grew, the doc didn't), or fine. Only the first two are yours.\n4. **Reconcile**, smallest edit that makes it true. Reconciliation is not a\n   rewrite, and it's not an excuse to restructure a document you happened to open.\n5. **Verify links resolve** if you moved or added any.\n\n**Check inventories before prose.** Prose gets reread when someone edits the\nfeature it describes; tables, diagrams, ADR indexes, project-layout blocks, and\nendpoint lists do not. Machine-like lists are where drift accumulates silently and\nwhere it's least visible — a paragraph that's half-wrong reads oddly, while a\ntable missing two rows reads perfectly.\n\n**A clean grep is not an all-clear.** Docs use shorthand, globs, and brace\nexpansion (`\u002Fapi\u002F{users,orders}`), so a literal grep can miss a line that\ndocuments exactly what you changed. When a document plausibly covers the area,\nopen the section and read it.\n\n## Accuracy: what you write is a claim\n\nBoth modes. A doc is a set of assertions about the code, and a sweep can introduce\nerrors as easily as it removes them — a confidently-worded wrong sentence outlives\nthe stale one it replaced, because it looks freshly maintained.\n\n- **No claim from recall.** Every factual sentence comes from something you read\n  this session. If you're describing what an endpoint does, open the handler.\n- **Enumerate from the source of truth.** Endpoints from the router file, scripts\n  from listing the directory, packages from the manifest, flags from the arg\n  parser. Don't rebuild a list from memory and spot-check it — build it from the\n  source and let it be complete by construction.\n- **Re-read your own doc diff against the code** before committing, with the same\n  scrutiny you'd give a code hunk. This is where a wrong claim gets caught.\n\n## Workflow: README\n\n### Step 1: Analyze the Project\n\nBefore writing, understand what exists:\n\n- Read the codebase structure, package.json\u002Fpyproject.toml\u002Fgo.mod, and existing docs\n- Identify the project type (library, CLI, web app, API, monorepo)\n- Identify the tech stack and key dependencies\n- Look for existing setup scripts, Docker files, or CI config\n- Check for a license file\n\n### Step 2: Write the README\n\nUse the template at [templates\u002Freadme.md](templates\u002Freadme.md). Adapt sections based on project type:\n\n**For a library\u002Fpackage**: Emphasize installation, quick start, API reference, and examples.\n**For a web app**: Emphasize prerequisites, setup, running locally, and environment config.\n**For a CLI tool**: Emphasize installation, usage with command examples, and configuration options.\n**For an API**: Emphasize endpoints overview, authentication, and link to full API docs.\n**For a monorepo**: Emphasize structure overview, per-package docs, and how packages relate.\n\nKey principles:\n- **Lead with value**: The first thing someone reads should explain what the project does and why they should care. Not the tech stack, not the folder structure.\n- **Working examples**: Every code snippet should be copy-pasteable and actually work.\n- **Mark unverified values outside the command, never inside it.** When you have to write a\n  command before you can confirm a value (a repo URL, a version, a port), the marker goes on\n  its own comment line above the block, or in prose beneath it — never inline in a command\n  token. `git clone \u003Crepo-url> ⚠️` is not a command: pasted, it clones into a directory\n  literally named `⚠️`. Write `# ⚠️ replace \u003Crepo-url> with the real remote` on the line\n  above, or use an obvious placeholder the shell cannot mistake for an argument. A snippet\n  that has been annotated into breaking is worse than one that says \"I need to read\n  `package.json` first\" — the reader trusts it and it fails on them.\n- **Prerequisites explicitly stated**: Don't assume Node 20, Python 3.12, or Docker are installed. State versions.\n- **From zero to running**: A new developer should go from `git clone` to a working local instance by following the README, without asking anyone.\n\n### Step 3: Verify\n\n- [ ] Can someone who has never seen this project understand what it does from the first paragraph?\n- [ ] Are all setup steps complete and in order?\n- [ ] Do code examples actually work?\n- [ ] Are prerequisites and versions specified?\n- [ ] Is there a way to verify the setup worked (e.g., \"you should see X\")?\n\n## Workflow: CONTRIBUTING.md\n\nSee [references\u002Fcontributing-guide.md](references\u002Fcontributing-guide.md) for the full guide on writing contributing docs.\n\n## Workflow: API Documentation\n\nWhen documenting an API:\n\n1. **Inventory endpoints**: List all routes from the codebase (read router files)\n2. **For each endpoint**: Method, path, description, request params\u002Fbody, response shape, error codes, auth requirements\n3. **Group by resource**: `\u002Fusers\u002F*`, `\u002Forders\u002F*`, `\u002Fproducts\u002F*`\n4. **Include examples**: Real request\u002Fresponse pairs, including error responses\n5. **Output format**: Markdown for simple APIs, OpenAPI\u002FSwagger spec for complex ones\n\nSuggest using the `api-design` skill if the API doesn't exist yet and needs designing.\n\n## Workflow: CHANGELOG\n\nFollow Keep a Changelog conventions:\n\n- Group changes under: Added, Changed, Deprecated, Removed, Fixed, Security\n- Newest version at the top\n- Link version headers to git comparison URLs\n- Write entries from the user's perspective, not the developer's\n\nSee [templates\u002Fchangelog.md](templates\u002Fchangelog.md) for the format.\n\n**First check whether the project generates this file.** A `release-please-config.json`,\n`.changeset\u002F`, `.releaserc*`, or `cliff.toml` means the changelog is derived from commit\nhistory, and hand-editing it — including keeping an `[Unreleased]` section alongside —\nthrows away the guarantee the tool exists to provide and reintroduces drift. There, the\nentry is the **commit subject** (for squash-merges, the PR title) and the work is writing\nthat well; the reasoning goes in the commit body, not the changelog. Say so and stop.\n\nWhen the changelog *is* hand-maintained, accumulate entries under `[Unreleased]` as\nchanges land. Writing them is this skill's work even when they must be reconstructed from\ngit history — read the log since the last tag, drop trivial commits (merges, typo fixes),\nand translate the rest into user-perspective entries under the sections above. Hand off\nonly the release mechanics (version choice, tagging, publish automation) to\n`release-management`.\n\n## Workflow: Inline Documentation\n\nFor code-level documentation (JSDoc, Python docstrings, Go doc comments):\n\n- **Document public APIs**: Every exported function, class, and type\n- **Skip obvious code**: Don't document `getName()` returning a name\n- **Document the why — at the altitude it belongs**: this is where inline docs go\n  wrong most often. The why of a *line* belongs on the line: why this parameter\n  exists, why this comparison is written the strange way it is, what the caller\n  can't see. The why of a *system* — why the component exists, which alternatives\n  were rejected, how it relates to other services — belongs in an ADR or\n  architecture doc, and the code carries a pointer to it:\n  `\u002F\u002F Triage state lives in a separate writable DB; see ADR-018.`\n  A design rationale pasted into a file header is unfindable (nobody greps source\n  for \"why two databases\"), unreviewable (it never gets the scrutiny an ADR gets),\n  and rots first — nobody re-reads a file header while editing line 300.\n- **Include examples** for non-obvious usage\n- **Document exceptions\u002Ferrors**: What can go wrong and under what conditions\n- **Use vocabulary the reader can resolve**: no phase names, checkpoint IDs, or\n  task codes that no versioned document defines (see The Documentation Strategy)\n\n## Principles Applied\n\n- **KISS**: Write the minimum documentation that makes the project usable. Don't over-document internals.\n- **DRY**: Don't duplicate information across docs. Link between documents instead.\n- **YAGNI**: Don't write architecture docs for a 200-line script. Match documentation depth to project complexity. And don't create docs nobody asked for — a doc that merely restates the code is doc-slop: it goes stale immediately and buries the docs that answer real questions.\n\n## Cross-Skill References\n\n- `architecture-design` — the ADR a system-level rationale belongs in, rather than a source-file header\n- `architecture-documentation` — C4 diagrams and docs-as-code for the architecture docs this skill points at\n- `verification-before-completion` — the doc-drift and publish gates that read the versioned\u002Finternal boundary above\n- `technical-debt-review` — a repo-wide doc-rot audit, as opposed to the drift from the change in front of you\n- `working-agreement` — owns the process document (where things live, session routines, tracking) and its validation; this skill writes the README and CONTRIBUTING text that link to it, and a sync sweep includes it when a change alters how the project is run\n","# Project Documentation\n\nHelp create and maintain documentation that makes a project understandable, usable, and contributable. Good documentation answers three questions: What is this? How do I use it? How do I contribute?\n\n## Document Types\n\nIdentify which documents the project needs based on context:\n\n| Document | When Needed | Audience |\n|----------|-------------|----------|\n| README.md | Every project | Users, contributors, evaluators |\n| CONTRIBUTING.md | Open source or team > 3 | New contributors |\n| API Documentation | Any project with an API | API consumers |\n| CHANGELOG.md | Any project with releases | Users upgrading between versions |\n| Architecture docs | Complex systems | New team members, future maintainers |\n| Inline docs (JSDoc\u002Fdocstrings) | Public APIs, complex logic | Developers reading the code |\n\nAsk the user which they need. If unsure, start with README — every project needs one.\nEvery document must answer a question someone actually has, so for each new one\nyou propose or are asked for, **ask the user who reads it and what question it\nanswers for them**, next to your draft or plan rather than in place of it.\n\nTwo modes use this skill. **Authoring** creates a document that doesn't exist yet\n(the four workflows below). **Sync** reconciles documents that already exist\nbecause a change made them wrong — that's the next section, and it's the mode you\nwant when someone says \"I changed X\" rather than \"write me a Y\".\n\n## The Documentation Strategy — What Ships and What Doesn't\n\nEstablish once with the user: **which artifacts are git-versioned, and which stay\ninternal.** Most projects accumulate both, and only one of them is readable by\nsomeone who has the repo and nothing else.\n\n| Typically versioned | Typically internal |\n|---|---|\n| README, contributing guide, API docs, changelog | Execution plans and phase breakdowns |\n| ADRs and architecture docs | Findings\u002Fbug logs kept during a work session |\n| Roadmaps the project chooses to publish | Scratchpads, handoff prompts, session notes |\n| Runbooks and operational docs | Anything under a gitignored directory |\n\nThis boundary is not bureaucracy — it decides what vocabulary the project's own\nartifacts are allowed to use. **A term is usable in a versioned file only if a\nversioned file defines it.** When a plan lives outside the repo, its phases,\ncheckpoints, and task codes name a conversation, and a reader hitting `Phase 2` or\n`CP1.3` in a comment or commit has nothing to resolve it against. Write what the\nterm means instead.\n\nThe reverse also holds and matters just as much: when a project *does* ship its\nplan or roadmap, referencing it is good practice, not a leak. Check which case\nyou're in rather than assuming either — `git ls-files` answers it.\n\n**On a greenfield project** nothing is tracked yet, so this is a decision to make,\nnot a fact to look up.\n\n**Exit condition** — one line, then write the document in the same response:\n*\"Nothing is tracked yet, so `\u003Cterm>` resolves to nothing for a reader; I've\nwritten the meaning instead. Worth deciding whether the plan itself ships.\"*\n\n**This is not a gate on authoring.** Raise the boundary, apply the safe default —\nmeanings rather than labels, which is never wrong and costs nothing to change — and\ndeliver the document. Never answer a request for docs with the boundary question\nalone: the user asked for a README, and a README that avoids unresolvable\nvocabulary is strictly better than a question. Ask when the answer would change\nwhat you write; otherwise state the assumption and write.\n\n`verification-before-completion`'s publish gate reads this boundary as its baseline\nwhen checking a staged diff.\n\n## Workflow: Sync After a Change\n\nDocs don't rot evenly. They rot where a change moved something a document names,\nand nobody reread that document. Work from the diff, not from a general sense\nthat the docs feel old:\n\n1. **Derive the identifiers.** From the diff, list what a reader could be relying\n   on: flags, env vars, config keys, endpoints, commands, script names, package\n   and directory names, install\u002Fsetup steps, public exported symbols. Include the\n   **old** names — those are what the docs still say.\n2. **Grep the doc set** for each: README, `docs\u002F`, and inline docs.\n3. **Triage each hit** — wrong (contradicts the code now), incomplete (the code\n   grew, the doc didn't), or fine. Only the first two are yours.\n4. **Reconcile**, smallest edit that makes it true. Reconciliation is not a\n   rewrite, and it's not an excuse to restructure a document you happened to open.\n5. **Verify links resolve** if you moved or added any.\n\n**Check inventories before prose.** Prose gets reread when someone edits the\nfeature it describes; tables, diagrams, ADR indexes, project-layout blocks, and\nendpoint lists do not. Machine-like lists are where drift accumulates silently and\nwhere it's least visible — a paragraph that's half-wrong reads oddly, while a\ntable missing two rows reads perfectly.\n\n**A clean grep is not an all-clear.** Docs use shorthand, globs, and brace\nexpansion (`\u002Fapi\u002F{users,orders}`), so a literal grep can miss a line that\ndocuments exactly what you changed. When a document plausibly covers the area,\nopen the section and read it.\n\n## Accuracy: what you write is a claim\n\nBoth modes. A doc is a set of assertions about the code, and a sweep can introduce\nerrors as easily as it removes them — a confidently-worded wrong sentence outlives\nthe stale one it replaced, because it looks freshly maintained.\n\n- **No claim from recall.** Every factual sentence comes from something you read\n  this session. If you're describing what an endpoint does, open the handler.\n- **Enumerate from the source of truth.** Endpoints from the router file, scripts\n  from listing the directory, packages from the manifest, flags from the arg\n  parser. Don't rebuild a list from memory and spot-check it — build it from the\n  source and let it be complete by construction.\n- **Re-read your own doc diff against the code** before committing, with the same\n  scrutiny you'd give a code hunk. This is where a wrong claim gets caught.\n\n## Workflow: README\n\n### Step 1: Analyze the Project\n\nBefore writing, understand what exists:\n\n- Read the codebase structure, package.json\u002Fpyproject.toml\u002Fgo.mod, and existing docs\n- Identify the project type (library, CLI, web app, API, monorepo)\n- Identify the tech stack and key dependencies\n- Look for existing setup scripts, Docker files, or CI config\n- Check for a license file\n\n### Step 2: Write the README\n\nUse the template at [templates\u002Freadme.md](templates\u002Freadme.md). Adapt sections based on project type:\n\n**For a library\u002Fpackage**: Emphasize installation, quick start, API reference, and examples.\n**For a web app**: Emphasize prerequisites, setup, running locally, and environment config.\n**For a CLI tool**: Emphasize installation, usage with command examples, and configuration options.\n**For an API**: Emphasize endpoints overview, authentication, and link to full API docs.\n**For a monorepo**: Emphasize structure overview, per-package docs, and how packages relate.\n\nKey principles:\n- **Lead with value**: The first thing someone reads should explain what the project does and why they should care. Not the tech stack, not the folder structure.\n- **Working examples**: Every code snippet should be copy-pasteable and actually work.\n- **Mark unverified values outside the command, never inside it.** When you have to write a\n  command before you can confirm a value (a repo URL, a version, a port), the marker goes on\n  its own comment line above the block, or in prose beneath it — never inline in a command\n  token. `git clone \u003Crepo-url> ⚠️` is not a command: pasted, it clones into a directory\n  literally named `⚠️`. Write `# ⚠️ replace \u003Crepo-url> with the real remote` on the line\n  above, or use an obvious placeholder the shell cannot mistake for an argument. A snippet\n  that has been annotated into breaking is worse than one that says \"I need to read\n  `package.json` first\" — the reader trusts it and it fails on them.\n- **Prerequisites explicitly stated**: Don't assume Node 20, Python 3.12, or Docker are installed. State versions.\n- **From zero to running**: A new developer should go from `git clone` to a working local instance by following the README, without asking anyone.\n\n### Step 3: Verify\n\n- [ ] Can someone who has never seen this project understand what it does from the first paragraph?\n- [ ] Are all setup steps complete and in order?\n- [ ] Do code examples actually work?\n- [ ] Are prerequisites and versions specified?\n- [ ] Is there a way to verify the setup worked (e.g., \"you should see X\")?\n\n## Workflow: CONTRIBUTING.md\n\nSee [references\u002Fcontributing-guide.md](references\u002Fcontributing-guide.md) for the full guide on writing contributing docs.\n\n## Workflow: API Documentation\n\nWhen documenting an API:\n\n1. **Inventory endpoints**: List all routes from the codebase (read router files)\n2. **For each endpoint**: Method, path, description, request params\u002Fbody, response shape, error codes, auth requirements\n3. **Group by resource**: `\u002Fusers\u002F*`, `\u002Forders\u002F*`, `\u002Fproducts\u002F*`\n4. **Include examples**: Real request\u002Fresponse pairs, including error responses\n5. **Output format**: Markdown for simple APIs, OpenAPI\u002FSwagger spec for complex ones\n\nSuggest using the `api-design` skill if the API doesn't exist yet and needs designing.\n\n## Workflow: CHANGELOG\n\nFollow Keep a Changelog conventions:\n\n- Group changes under: Added, Changed, Deprecated, Removed, Fixed, Security\n- Newest version at the top\n- Link version headers to git comparison URLs\n- Write entries from the user's perspective, not the developer's\n\nSee [templates\u002Fchangelog.md](templates\u002Fchangelog.md) for the format.\n\n**First check whether the project generates this file.** A `release-please-config.json`,\n`.changeset\u002F`, `.releaserc*`, or `cliff.toml` means the changelog is derived from commit\nhistory, and hand-editing it — including keeping an `[Unreleased]` section alongside —\nthrows away the guarantee the tool exists to provide and reintroduces drift. There, the\nentry is the **commit subject** (for squash-merges, the PR title) and the work is writing\nthat well; the reasoning goes in the commit body, not the changelog. Say so and stop.\n\nWhen the changelog *is* hand-maintained, accumulate entries under `[Unreleased]` as\nchanges land. Writing them is this skill's work even when they must be reconstructed from\ngit history — read the log since the last tag, drop trivial commits (merges, typo fixes),\nand translate the rest into user-perspective entries under the sections above. Hand off\nonly the release mechanics (version choice, tagging, publish automation) to\n`release-management`.\n\n## Workflow: Inline Documentation\n\nFor code-level documentation (JSDoc, Python docstrings, Go doc comments):\n\n- **Document public APIs**: Every exported function, class, and type\n- **Skip obvious code**: Don't document `getName()` returning a name\n- **Document the why — at the altitude it belongs**: this is where inline docs go\n  wrong most often. The why of a *line* belongs on the line: why this parameter\n  exists, why this comparison is written the strange way it is, what the caller\n  can't see. The why of a *system* — why the component exists, which alternatives\n  were rejected, how it relates to other services — belongs in an ADR or\n  architecture doc, and the code carries a pointer to it:\n  `\u002F\u002F Triage state lives in a separate writable DB; see ADR-018.`\n  A design rationale pasted into a file header is unfindable (nobody greps source\n  for \"why two databases\"), unreviewable (it never gets the scrutiny an ADR gets),\n  and rots first — nobody re-reads a file header while editing line 300.\n- **Include examples** for non-obvious usage\n- **Document exceptions\u002Ferrors**: What can go wrong and under what conditions\n- **Use vocabulary the reader can resolve**: no phase names, checkpoint IDs, or\n  task codes that no versioned document defines (see The Documentation Strategy)\n\n## Principles Applied\n\n- **KISS**: Write the minimum documentation that makes the project usable. Don't over-document internals.\n- **DRY**: Don't duplicate information across docs. Link between documents instead.\n- **YAGNI**: Don't write architecture docs for a 200-line script. Match documentation depth to project complexity. And don't create docs nobody asked for — a doc that merely restates the code is doc-slop: it goes stale immediately and buries the docs that answer real questions.\n\n## Cross-Skill References\n\n- `architecture-design` — the ADR a system-level rationale belongs in, rather than a source-file header\n- `architecture-documentation` — C4 diagrams and docs-as-code for the architecture docs this skill points at\n- `verification-before-completion` — the doc-drift and publish gates that read the versioned\u002Finternal boundary above\n- `technical-debt-review` — a repo-wide doc-rot audit, as opposed to the drift from the change in front of you\n- `working-agreement` — owns the process document (where things live, session routines, tracking) and its validation; this skill writes the README and CONTRIBUTING text that link to it, and a sync sweep includes it when a change alters how the project is run\n",{"name":5,"description":7,"when_to_use":57},"Triggers: write a README, document this project, contributing guide, changelog, API docs, this needs docs, docstrings, do the docs still match, are the docs still accurate, doc sweep, stale docs, doc drift, I renamed X — what else needs updating.","main","800dc9ad0ca2914d6ad15b8c5159d9b57bb104c2","plugins\u002Fdevops\u002Fskills\u002Fproject-documentation","https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills","https:\u002F\u002Fgithub.com\u002FSWEStash","A stash of things we felt like building","2026-11-12 00:14:33",{"source":8,"skillName":5,"commands":66,"prompt":76,"zipAvailable":77},[67,70,73],{"tool":68,"command":69},"npx","npx skills add SWEStash\u002Fswe-workflow-skills --skill project-documentation",{"tool":71,"command":72},"bunx","bunx skills add SWEStash\u002Fswe-workflow-skills --skill project-documentation",{"tool":74,"command":75},"pnpm","pnpm dlx skills add SWEStash\u002Fswe-workflow-skills --skill project-documentation","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fdevops\u002Fskills\u002Fproject-documentation\u002FSKILL.md",true,[79,85,89,93],{"path":80,"resourceType":81,"resourceTypeDesc":82,"sizeBytes":83,"sourceHtmlUrl":84},"evals\u002Fevals.json","REFERENCE","参考文档",8675,"https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fdevops\u002Fskills\u002Fproject-documentation\u002Fevals\u002Fevals.json",{"path":86,"resourceType":81,"resourceTypeDesc":82,"sizeBytes":87,"sourceHtmlUrl":88},"references\u002Fcontributing-guide.md",3064,"https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fdevops\u002Fskills\u002Fproject-documentation\u002Freferences\u002Fcontributing-guide.md",{"path":90,"resourceType":81,"resourceTypeDesc":82,"sizeBytes":91,"sourceHtmlUrl":92},"templates\u002Fchangelog.md",1786,"https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fdevops\u002Fskills\u002Fproject-documentation\u002Ftemplates\u002Fchangelog.md",{"path":94,"resourceType":81,"resourceTypeDesc":82,"sizeBytes":95,"sourceHtmlUrl":96},"templates\u002Freadme.md",2723,"https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fdevops\u002Fskills\u002Fproject-documentation\u002Ftemplates\u002Freadme.md",[98,137,159,183,216,242],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":117,"publishedAt":52},"01M6JQFADV3T1MS9V1BNZS1232","writing-skills","Use when authoring, editing, or reviewing a skill in this library — a new SKILL.md, one that under-triggers, or hardening an existing one. Covers description and listing-budget rules, frontmatter, progressive disclosure, the 3-eval rule, and pressure-testing against rationalizations.","https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-skills\u002FSKILL.md",[104,107,110,111,114],{"categoryNo":105,"categoryName":106,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":108,"categoryName":109,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":112,"categoryName":113,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000036","内容创作者",{"categoryNo":115,"categoryName":116,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000040","财务",[118,119,120,121,44,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136],"writing","writing skills","testing","eval","edit","Budget","authoring","new skill","library","frontmatter","editing","triggers","use","Existing","Rules","write a skill","when","listing","progressive disclosure",{"skillNo":138,"name":139,"nameZh":6,"description":140,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":141,"categories":142,"keywords":144,"publishedAt":52},"01M6JQF5DGMXPMQQVZBP8DH9SY","working-agreement","Define and validate how a multi-session project is run — where plans, status and decisions live, session routines, new work, milestone close. README\u002FCONTRIBUTING → project-documentation.","https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fskills\u002Fworking-agreement\u002FSKILL.md",[143],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[145,34,146,147,148,33,149,150,45,48,151,50,152,153,154,155,156,157,129,158],"working agreement","definition of done","done","milestone","work","progress","close","sync","status","live","do","README","session","routines",{"skillNo":160,"name":161,"nameZh":6,"description":162,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":163,"categories":164,"keywords":166,"publishedAt":52},"01M6JQF0SMRHN82RBSWMABC4J0","verification-before-completion","Evidence gate before any claim that work is done, fixed, passing, or deployed. Route here when a message declares the work finished or asks to commit, push, merge, ship, or close it out, including a brief sign-off, and before git-workflow or release-management act on it. Writing the commit message or PR text itself → git-workflow.","https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fskills\u002Fverification-before-completion\u002FSKILL.md",[165],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[167,168,169,170,171,172,118,173,147,174,175,176,149,177,151,178,179,180,181,182],"verification","verification before completion","brief","ready","fix","claim","workflow","commit","text","route","message","merge","release","git","act","ship",{"skillNo":184,"name":185,"nameZh":6,"description":186,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":187,"categories":188,"keywords":196,"publishedAt":52},"01M6JQEVGE9NJZ11DV60AE6VWC","ui-ux-design","Design user experiences from an engineer's perspective — user flows, wireframes, interaction patterns, responsive strategy, navigation, loading\u002Ferror\u002Fempty states. Triggers: design the UI, user flow, wireframe, how should this screen look, loading state, error state, empty state, responsive design, navigation, page layout, form design, mockup.","https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fskills\u002Fui-ux-design\u002FSKILL.md",[189,192,193],{"categoryNo":190,"categoryName":191,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":194,"categoryName":195,"taxonomyType":29,"taxonomyTypeDesc":30},"01JBSEEDCAT000000000000032","设计师",[197,198,199,200,201,202,203,204,205,206,207,208,45,209,210,211,212,213,214,215],"design","ux","ui","ui ux design","error","states","loading","flows","engineer","interaction","layout","responsive design","screen","flow","patterns","mockup","responsive","form","page",{"skillNo":217,"name":218,"nameZh":6,"description":219,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":220,"categories":221,"keywords":224,"publishedAt":52},"01M6JQEN4HVFTZWQYWGTDS76K9","threat-modeling","Design-time security analysis of a system or feature before it's built — trust boundaries, attack surface, STRIDE per element, abuse cases, prioritized mitigations that become security requirements. Triggers: threat model, STRIDE, trust boundary, attack surface, what could go wrong security-wise, security design review, abuse case, secure this design, security requirements. Reviewing EXISTING code\u002Fconfig for vulnerabilities → security-audit; use this skill while the design is still on the whiteboard.","https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fskills\u002Fthreat-modeling\u002FSKILL.md",[222,223],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},[225,226,227,228,229,230,197,231,232,233,234,43,235,47,236,237,238,239,240,241],"modeling","threat modeling","threat","model","time","element","whiteboard","security analysis","analysis","code","threat model","security-audit","secure","config","go","security","trust",{"skillNo":243,"name":244,"nameZh":6,"description":245,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":246,"categories":247,"keywords":253,"publishedAt":52},"01M6JQEFT7VT3FQM16170EG9FW","test-suite-design","Design comprehensive test suites for existing code — strategy across unit\u002Fintegration\u002Fe2e, fixtures, factories, helpers. Triggers: add tests, write tests for, increase coverage, test this module, testing strategy, test plan, what tests do I need, test infrastructure, test helpers, this has no tests. Not for TDD — use tdd-workflow.","https:\u002F\u002Fgithub.com\u002FSWEStash\u002Fswe-workflow-skills\u002Fblob\u002Fmain\u002Fskills\u002Ftest-suite-design\u002FSKILL.md",[248,249,250,251,252],{"categoryNo":105,"categoryName":106,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":190,"categoryName":191,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},{"categoryNo":27,"categoryName":28,"taxonomyType":29,"taxonomyTypeDesc":30},{"categoryNo":194,"categoryName":195,"taxonomyType":29,"taxonomyTypeDesc":30},[197,254,255,256,257,258,120,259,260,173,234,261,262,44,263,264,155,265,266,129],"test suite","test","test suite design","coverage","unit","write tests","testing strategy","across","plan","add","infrastructure","test plan","for"]