[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7ASQB3CTKMKDNAXD9DCF1YC":3,"skill-same:01M7ASQB3CTKMKDNAXD9DCF1YC":52},{"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":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M7ASQB3CTKMKDNAXD9DCF1YC","writing-design-docs",null,"Use when the user wants to write a problem-statement design doc, says \"let's plan a feature properly\" \u002F \"write a design doc\" \u002F \"I'm thinking about how to do X\" for a non-trivial X, or before committing to a non-obvious technical direction","ozzycodes2\u002Fclaudellum","ozzycodes2","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F21285094?v=4","01M7ASJ57KTP519F96S4QGM7C5","Osniel Quintana","01M7ASJ589JS8S075AA92Y08S4",1,"MIT","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fwriting-design-docs\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: writing-design-docs\ndescription: Use when the user wants to write a problem-statement design doc, says \"let's plan a feature properly\" \u002F \"write a design doc\" \u002F \"I'm thinking about how to do X\" for a non-trivial X, or before committing to a non-obvious technical direction\n---\n\n# Writing Design Docs\n\nDraft a problem-statement design doc — value comes from the writing process itself, not the artifact. Writing exposes knowledge gaps and forces you to articulate values; readers then have something concrete to push back on.\n\n**Core principle:** lead with the problem, not the solution. A doc opening with \"we'll use Tool X\" has skipped the work that makes the rest trustworthy.\n\nSource: \u003Chttps:\u002F\u002Fblog.ceejbot.com\u002Fposts\u002Fdesign-docs\u002F>.\n\n## When to use\n\n- Non-trivial technical direction needs choosing.\n- More than one person (or the user with their future self) needs shared understanding.\n- Tradeoffs are not obvious and would otherwise devolve into a preference argument.\n- Before committing to a path you'd be reluctant to walk back.\n\n**Skip if:** work is small enough that \"just do it\" is right, or the path is genuinely obvious.\n\n## The six components\n\nWalk these in order. Don't skip ahead.\n\n### 1. Problem statement\n- What's broken or missing in the current system?\n- What behaviour change is wanted?\n- What does success look like — measurable, ideally?\n- Explicitly: what are we **not** addressing?\n\n### 2. Background and research\n- How does the existing system actually work today?\n- What did investigation turn up — quantifiable where possible (scale, growth rate, failure mode, constraint)?\n- Written so a reader unfamiliar with this corner can follow the rest.\n\n### 3. Project values\n- The rubric. Resilience, delivery speed, privacy, cost, simplicity, maintainability, blast radius — pick the few that matter for this decision.\n- Without stated values, the options comparison becomes \"I prefer X\" vs \"I prefer Y\".\n\n### 4. Options considered\n- 2–3 serious alternatives.\n- For each: how it works, what it costs, how it scores against §3 values.\n- If only one option exists, explain why — what was ruled out, on what grounds.\n- Honest tradeoffs. If an option has a real downside, name it.\n\n### 5. Recommended solution with rationale\n- The choice, plus reasoning tracing back to the values.\n- A reader with **different** value priorities should see how their conclusion would differ. Make the reasoning legible enough to be argued with.\n\n### 6. Open questions\n- Known unknowns.\n- Decisions deferred and why.\n- Areas needing more research.\n- Surfacing these is a strength, not a weakness — where readers help most.\n\n## Process\n\nMove through stages, not all at once:\n\n1. **Personal research** — fill in §1, §2, §3 alone. Get the problem clear before talking to anyone.\n2. **1–2 trusted advisors** — pressure-test framing and values before going wider.\n3. **Domain expert review** — for areas you don't own.\n4. **Stakeholder preview** — people whose work this affects.\n5. **Wider audience** — only after the doc survives the prior stages.\n\nEach stage finds different gaps. Skipping stages means finding them all at once, in front of the wrong audience.\n\n## Pitfalls\n\n| Pitfall | What goes wrong | What to do instead |\n|---|---|---|\n| Solution-first writing | Doc opens with \"use Tool X\", no evaluation criteria. Reviewers can only nod or push back without ammunition. | Write §1–§3 *before* naming a tool. |\n| Missing reasoning | States the choice but not *why* it follows from the values. Reads as opinion. | Every recommendation traces back to a §3 value. |\n| Unstated values | §3 skipped or vague. Tradeoff debates become preference fights. | Write values explicitly. If reviewers disagree on values, surface that *first*. |\n| Approval-seeking | Polishing until the doc looks confident. Open questions disappear. | Keep §6 honest. A doc with open questions invites help; one without invites rubber-stamping. |\n\n## Output\n\nUse the template at `template.md` in this skill directory. Drop it into the project as `docs\u002Fdesign\u002F\u003Ctopic>.md` (or wherever the project keeps design docs) and fill in stage by stage.\n\nWhen drafting interactively, work one section at a time — don't generate the whole doc in one shot. The shared understanding *is* the value, and it forms only through the conversation.\n\nFor diagrams, follow `..\u002F..\u002Freferences\u002Fdiagrams.md`.\n\nOffer `review-doc` when a draft is complete.\n\n## Anti-patterns when drafting\n\n| Don't | Why |\n|---|---|\n| Generate all six sections at once | The writing process is the point. Draft §1, confirm, then §2, etc. |\n| Hand-wave §3 (values) | Without values, §4 and §5 collapse into preference. |\n| Hide the recommendation in §1 | \"We're going to do X\" before §2–§4 makes everything after post-hoc rationalization. |\n| Skip §6 to look confident | Honest open questions invite help. Polished docs invite rubber-stamping. |\n| Use \"we should\" without saying *why we should* | The why is the doc's whole reason for existing. |\n","# Writing Design Docs\n\nDraft a problem-statement design doc — value comes from the writing process itself, not the artifact. Writing exposes knowledge gaps and forces you to articulate values; readers then have something concrete to push back on.\n\n**Core principle:** lead with the problem, not the solution. A doc opening with \"we'll use Tool X\" has skipped the work that makes the rest trustworthy.\n\nSource: \u003Chttps:\u002F\u002Fblog.ceejbot.com\u002Fposts\u002Fdesign-docs\u002F>.\n\n## When to use\n\n- Non-trivial technical direction needs choosing.\n- More than one person (or the user with their future self) needs shared understanding.\n- Tradeoffs are not obvious and would otherwise devolve into a preference argument.\n- Before committing to a path you'd be reluctant to walk back.\n\n**Skip if:** work is small enough that \"just do it\" is right, or the path is genuinely obvious.\n\n## The six components\n\nWalk these in order. Don't skip ahead.\n\n### 1. Problem statement\n- What's broken or missing in the current system?\n- What behaviour change is wanted?\n- What does success look like — measurable, ideally?\n- Explicitly: what are we **not** addressing?\n\n### 2. Background and research\n- How does the existing system actually work today?\n- What did investigation turn up — quantifiable where possible (scale, growth rate, failure mode, constraint)?\n- Written so a reader unfamiliar with this corner can follow the rest.\n\n### 3. Project values\n- The rubric. Resilience, delivery speed, privacy, cost, simplicity, maintainability, blast radius — pick the few that matter for this decision.\n- Without stated values, the options comparison becomes \"I prefer X\" vs \"I prefer Y\".\n\n### 4. Options considered\n- 2–3 serious alternatives.\n- For each: how it works, what it costs, how it scores against §3 values.\n- If only one option exists, explain why — what was ruled out, on what grounds.\n- Honest tradeoffs. If an option has a real downside, name it.\n\n### 5. Recommended solution with rationale\n- The choice, plus reasoning tracing back to the values.\n- A reader with **different** value priorities should see how their conclusion would differ. Make the reasoning legible enough to be argued with.\n\n### 6. Open questions\n- Known unknowns.\n- Decisions deferred and why.\n- Areas needing more research.\n- Surfacing these is a strength, not a weakness — where readers help most.\n\n## Process\n\nMove through stages, not all at once:\n\n1. **Personal research** — fill in §1, §2, §3 alone. Get the problem clear before talking to anyone.\n2. **1–2 trusted advisors** — pressure-test framing and values before going wider.\n3. **Domain expert review** — for areas you don't own.\n4. **Stakeholder preview** — people whose work this affects.\n5. **Wider audience** — only after the doc survives the prior stages.\n\nEach stage finds different gaps. Skipping stages means finding them all at once, in front of the wrong audience.\n\n## Pitfalls\n\n| Pitfall | What goes wrong | What to do instead |\n|---|---|---|\n| Solution-first writing | Doc opens with \"use Tool X\", no evaluation criteria. Reviewers can only nod or push back without ammunition. | Write §1–§3 *before* naming a tool. |\n| Missing reasoning | States the choice but not *why* it follows from the values. Reads as opinion. | Every recommendation traces back to a §3 value. |\n| Unstated values | §3 skipped or vague. Tradeoff debates become preference fights. | Write values explicitly. If reviewers disagree on values, surface that *first*. |\n| Approval-seeking | Polishing until the doc looks confident. Open questions disappear. | Keep §6 honest. A doc with open questions invites help; one without invites rubber-stamping. |\n\n## Output\n\nUse the template at `template.md` in this skill directory. Drop it into the project as `docs\u002Fdesign\u002F\u003Ctopic>.md` (or wherever the project keeps design docs) and fill in stage by stage.\n\nWhen drafting interactively, work one section at a time — don't generate the whole doc in one shot. The shared understanding *is* the value, and it forms only through the conversation.\n\nFor diagrams, follow `..\u002F..\u002Freferences\u002Fdiagrams.md`.\n\nOffer `review-doc` when a draft is complete.\n\n## Anti-patterns when drafting\n\n| Don't | Why |\n|---|---|\n| Generate all six sections at once | The writing process is the point. Draft §1, confirm, then §2, etc. |\n| Hand-wave §3 (values) | Without values, §4 and §5 collapse into preference. |\n| Hide the recommendation in §1 | \"We're going to do X\" before §2–§4 makes everything after post-hoc rationalization. |\n| Skip §6 to look confident | Honest open questions invite help. Polished docs invite rubber-stamping. |\n| Use \"we should\" without saying *why we should* | The why is the doc's whole reason for existing. |\n",{"name":5,"description":7},"main","a3f19bcc313571bff79dca391a83f9c4d38bb335","technical-writing\u002Fskills\u002Fwriting-design-docs",0,"https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum","https:\u002F\u002Fgithub.com\u002Fozzycodes2","Software Engineer | Engineering Manager | AI whisperer | ☕Enjoyer","2026-11-14 04:50:11",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add ozzycodes2\u002Fclaudellum --skill writing-design-docs",{"tool":38,"command":39},"bunx","bunx skills add ozzycodes2\u002Fclaudellum --skill writing-design-docs",{"tool":41,"command":42},"pnpm","pnpm dlx skills add ozzycodes2\u002Fclaudellum --skill writing-design-docs","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fwriting-design-docs\u002FSKILL.md",true,[46],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"template.md","REFERENCE","参考文档",2279,"https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fwriting-design-docs\u002Ftemplate.md",[53,60,67,74,81,88],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M7ASQ6JD4QRV5ZKK2QME401Y","write-doc","Use when the user asks to write or draft a README, ADR, runbook, tutorial, how-to, explanation, or reference doc, or a caller passes \"type ADR\" or \"type README\". Picks the type, fills a template, adds diagrams. RFCs and design docs belong to writing-design-docs.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fwrite-doc\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M7ASQ1VWNVP1RE7M5D4G2QMG","review-doc","Use when the user asks to review, critique, score, grade, or \"how good is this doc\" for a Markdown doc or pasted text. Read-only. Scores it on the 20 Practical Prose dimensions and emits a findings table. Does not edit; fix-doc applies the findings next.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Freview-doc\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M7ASPWST208JZNR7HF7J6KMV","fix-doc","Use when the user asks to fix, edit for prose quality, polish, tighten, humanize, or de-slop a Markdown doc or pasted text, or says \"make this read less AI\". Applies review-doc findings, generates flagged diagrams, lists substantive issues for the author, then runs the AI-tell pass last. Modifies the target.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Ffix-doc\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M7ASPS6Y9ZGK9KCDHNPDR75A","create-slides","Use when the user asks for a slide deck, presentation, talk, or slides from a document, report, PR, notes, or topic. Builds one self-contained Machinify-branded HTML deck in a minimalist style, with headline-plus-visual slides, speaker notes, and every diagram drawn by architecture-design:create-diagram.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Ftechnical-writing\u002Fskills\u002Fcreate-slides\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M7ASPAKFY045KHR92Y4QFTWV","start-session","Open a Claude Code working session in a fresh, isolated git worktree, so the user can start a task with a single \u002Fstart-session \u003Cname>. Use at the START of a session when the user says \"start session\", \"start a worktree\", \"spin up a worktree for ABC-123\", \"begin work on \u003Cticket>\", or passes a name\u002Fticket to work under. Creates and ENTERS a worktree via the EnterWorktree tool (never `git worktree add`) under .claude\u002Fworktrees\u002F, named exactly after the argument, on a local branch `worktree-\u003Cargument>`. Reports what the worktree inherited (`.worktreeinclude` copies, symlinked node_modules) and whether its `.env` still points at the main checkout's stack. If the argument is a JIRA key (e.g. ABC-123, PROJ-1505), also loads that story with the Atlassian CLI (`acli`) when available and summarizes the implementation ask. Also renames the session to the argument (the same effect as `\u002Frename \u003CNAME>`) so it's easy to find in `\u002Fresume`. Then stops and waits — it sets up the workspace and context, it does not implement.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Fsession-mgmt\u002Fskills\u002Fstart-session\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M7ASNSKFMMXSG954AEMW8HAZ","exit-session","Tear down the ephemeral resources a Claude Code working session created, then quit the CLI — so the user can wrap up with a single \u002Fexit-session. Use when the user says \"exit session\", \"clean up this session\", \"tear down everything\", \"wrap up and clean up resources\", \"remove the worktree and scratch\", \"stop the background processes\", \"shut down the stack\", \"clean up the agent worktrees\", or asks to clean up after finishing a task — even if they only name one resource (assume they want the full sweep unless they scope it). Runs teardown permission-free: stops background processes and dev servers, Docker\u002Fcompose stacks plus their volumes, networks and images, local Tilt\u002FKubernetes, git worktrees, merged local branches, and temp\u002Fscratch files without prompting, then exits the CLI. Covers the worktrees and Docker resources left behind by subagents spawned during the session, not just the primary agent's own worktree — both determined from git locks and Docker labels rather than from recall. Never touches resources a still-live session holds.","https:\u002F\u002Fgithub.com\u002Fozzycodes2\u002Fclaudellum\u002Fblob\u002Fmain\u002Fsession-mgmt\u002Fskills\u002Fexit-session\u002FSKILL.md",[],[]]