{"id":"29423fe9-906f-48ff-b512-39f9354c378a","shortId":"ND2CUc","kind":"skill","title":"plan","tagline":"Use when a task is multi-step, ambiguous, or high-impact and you need an executable implementation plan before editing code.","description":"task = $ARGUMENTS\n\nProduce the minimum artifact that prevents the executor from going wrong. The executor starts with an empty context window: they get this plan and the codebase, nothing else. Every ambiguity becomes a wrong guess they make confidently.\n\nMatch depth to complexity. A 3-file bug fix needs a paragraph, not a document. If you could describe the diff in one sentence, skip the plan entirely.\n\n## Exploration\n\nExplore until you can articulate *why* one approach beats alternatives — then stop and write. If you can't articulate the tradeoffs, you haven't explored enough. If you're still reading files after the picture is clear, you've explored too much. External-axis stop: a borrowable pattern is identified, or you've confirmed nobody solved it cleanly — inventing is the fallback, not the default.\n\nTwo axes, pursued concurrently via read-only subagents that return summaries (not raw file dumps):\n\n- **Codebase** — existing implementations, patterns, conventions. For every new pattern the plan introduces, cite the precedent `file:line` the executor should mirror. Without the citation, the executor will reinvent — even when the precedent exists.\n- **External** — web search for how others solved this. Libraries, vendor docs, open-source implementations. Prefer borrowing a named approach over inventing; name the source (URL or library) in the plan.\n\n## Decomposition\n\nChoose based on task shape, not habit. Default to vertical slice; switch when the task clearly fits another:\n\n| Strategy | When | Risk it mitigates |\n|----------|------|---------------------|\n| **Vertical slice** | Multiple independent behaviors | Integration surprises — each slice proves end-to-end |\n| **Walking skeleton** | Uncertain integration path | Late-stage \"it doesn't connect\" — proves wiring first |\n| **Layer-by-layer** | Clear layers, different complexity zones | Allows parallel work; natural when data model drives everything |\n\n## Specificity\n\nThe hard part of planning is identifying the *surface of change* — which files, which functions, which call sites. Once the surface is named, the edits are obvious. Name concrete files and functions; describe *what* changes and *why*; reference precedent for the pattern to follow. Leave *how* to the executor — they need goals and constraints, not pseudocode.\n\nWhen a step would otherwise contain a guess, ask the user before saving. The plan is a closed contract — the executor cannot resolve ambiguity, only act on it.\n\n- **Under-specified:** `Add a rate limiter to the API.`\n- **Over-specified:** Pseudocode of the rate-limit check, variable names, HTTP status codes.\n- **Calibrated:** `Add per-user rate limiting to authenticated endpoints. New middleware in src/api/middleware/ratelimit.py following the pattern of src/api/middleware/auth.py (middleware class + decorator registration in src/api/app.py:42). Use the existing Redis client from src/infra/redis.py.`\n\nLitmus tests:\n- \"Could the executor start in the wrong file?\" → be more specific.\n- \"Could the executor implement this without reading my plan?\" → the step is too detailed.\n\n## Plan Format\n\nRequired:\n\n- **Goal** — One sentence. What exists after that didn't before.\n- **Files** — Exact paths with `[NEW]`/`[MOD]`/`[DEL]` prefix. Map the change surface before decomposing into steps.\n- **Steps** — Ordered, checkboxed (`- [ ]`), each naming the file(s) it touches.\n- **Verification** — Per-step: command + expected result. Final: acceptance criteria the executor checks before declaring done.\n\nAdd when the task warrants:\n\n- **Background** — The *why*, when not obvious from the goal.\n- **Key Concepts** — Domain terms, sentinel values, non-obvious patterns. Table format.\n- **Approach & Rejected Alternatives** — What you chose and rejected, with rationale. Prevents re-litigating decisions.\n- **Edge Cases** — The 3–5 most likely failure modes and how the plan handles each. If you can't name them, you haven't understood the problem deeply enough.\n- **Risks** — Only non-obvious ones with mitigations.\n- **Work Decomposition** — For `/orch`: which steps run in parallel vs. sequential, and why.\n\n## Self-Review\n\nBefore saving, check:\n- Every goal-implied change has a step.\n- No placeholders survive: `TBD`, \"implement later\", \"add error handling\" without specifics. No open questions — every ambiguity was resolved with the user before save.\n- Function/type names referenced across steps match each other and the codebase.\n\n## Save & Handoff\n\nSave to `docs/plans/<type>-<short-name>.md` (adapt to project conventions if established). Types: `feat-`, `fix-`, `refactor-`, `chore-`.\n\nTo update an existing plan, re-read it, diff against new requirements, and revise in place.\n\nHand off to `/code` for single-agent execution or `/orch` for parallel work.","tags":["plan","dotclaude","jhostalek","agent-skills","ai-coding","anthropic","claude","claude-code","claude-code-skills","code-review","codex-cli","cursor"],"capabilities":["skill","source-jhostalek","skill-plan","topic-agent-skills","topic-ai-coding","topic-anthropic","topic-claude","topic-claude-code","topic-claude-code-skills","topic-code-review","topic-codex-cli","topic-cursor","topic-developer-tools","topic-git-workflow","topic-multi-agent"],"categories":["dotclaude"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/JHostalek/dotclaude/plan","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add JHostalek/dotclaude","source_repo":"https://github.com/JHostalek/dotclaude","install_from":"skills.sh"}},"qualityScore":"0.454","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 8 github stars · SKILL.md body (4,780 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:16.505Z","embedding":null,"createdAt":"2026-05-18T13:20:33.542Z","updatedAt":"2026-05-18T19:13:16.505Z","lastSeenAt":"2026-05-18T19:13:16.505Z","tsv":"'/code':711 '/orch':616,718 '3':69,579 '42':445 '5':580 'accept':527 'across':666 'act':392 'adapt':680 'add':398,421,535,646 'agent':715 'allow':301 'altern':102,563 'ambigu':10,56,390,655 'anoth':257 'api':404 'approach':100,227,561 'argument':26 'articul':97,111 'artifact':30 'ask':375 'authent':428 'axe':160 'axi':137 'background':540 'base':241 'beat':101 'becom':57 'behavior':267 'borrow':140,224 'bug':71 'calibr':420 'call':327 'cannot':388 'case':577 'chang':321,345,503,636 'check':414,531,631 'checkbox':511 'choos':240 'chore':690 'chose':566 'citat':198 'cite':187 'class':440 'clean':151 'clear':129,255,296 'client':450 'close':384 'code':24,419 'codebas':52,175,673 'command':523 'complex':67,299 'concept':550 'concret':339 'concurr':162 'confid':63 'confirm':147 'connect':288 'constraint':364 'contain':372 'context':44 'contract':385 'convent':179,683 'could':81,455,466 'criteria':528 'data':306 'decis':575 'declar':533 'decompos':506 'decomposit':239,614 'decor':441 'deepli':603 'default':158,247 'del':499 'depth':65 'describ':82,343 'detail':479 'didn':490 'diff':84,700 'differ':298 'doc':218 'docs/plans':678 'document':78 'doesn':286 'domain':551 'done':534 'drive':308 'dump':174 'edg':576 'edit':23,335 'els':54 'empti':43 'end':274,276 'end-to-end':273 'endpoint':429 'enough':118,604 'entir':91 'error':647 'establish':685 'even':203 'everi':55,181,632,654 'everyth':309 'exact':494 'execut':19,716 'executor':34,39,193,200,359,387,457,468,530 'exist':176,207,448,487,694 'expect':524 'explor':92,93,117,132 'extern':136,208 'external-axi':135 'failur':583 'fallback':155 'feat':687 'file':70,124,173,190,323,340,462,493,515 'final':526 'first':291 'fit':256 'fix':72,688 'follow':354,434 'format':481,560 'function':325,342 'function/type':663 'get':47 'go':36 'goal':362,483,548,634 'goal-impli':633 'guess':60,374 'habit':246 'hand':708 'handl':589,648 'handoff':675 'hard':312 'haven':115,598 'high':13 'high-impact':12 'http':417 'identifi':143,317 'impact':14 'implement':20,177,222,469,644 'impli':635 'independ':266 'integr':268,280 'introduc':186 'invent':152,229 'key':549 'late':283 'late-stag':282 'later':645 'layer':293,295,297 'layer-by-lay':292 'leav':355 'librari':216,235 'like':582 'limit':401,413,426 'line':191 'litig':574 'litmus':453 'make':62 'map':501 'match':64,668 'md':679 'middlewar':431,439 'minimum':29 'mirror':195 'mitig':262,612 'mod':498 'mode':584 'model':307 'much':134 'multi':8 'multi-step':7 'multipl':265 'name':226,230,333,338,416,513,595,664 'natur':304 'need':17,73,361 'new':182,430,497,702 'nobodi':148 'non':556,608 'non-obvi':555,607 'noth':53 'obvious':337,545,557,609 'one':86,99,484,610 'open':220,652 'open-sourc':219 'order':510 'other':213 'otherwis':371 'over-specifi':405 'paragraph':75 'parallel':302,621,720 'part':313 'path':281,495 'pattern':141,178,183,352,436,558 'per':423,521 'per-step':520 'per-us':422 'pictur':127 'place':707 'placehold':641 'plan':1,21,49,90,185,238,315,381,474,480,588,695 'preced':189,206,349 'prefer':223 'prefix':500 'prevent':32,571 'problem':602 'produc':27 'project':682 'prove':272,289 'pseudocod':366,408 'pursu':161 'question':653 'rate':400,412,425 'rate-limit':411 'rational':570 'raw':172 're':121,573,697 're-litig':572 're-read':696 'read':123,165,472,698 'read-on':164 'redi':449 'refactor':689 'refer':348 'referenc':665 'registr':442 'reinvent':202 'reject':562,568 'requir':482,703 'resolv':389,657 'result':525 'return':169 'review':628 'revis':705 'risk':260,605 'run':619 'save':379,630,662,674,676 'search':210 'self':627 'self-review':626 'sentenc':87,485 'sentinel':553 'sequenti':623 'shape':244 'singl':714 'single-ag':713 'site':328 'skeleton':278 'skill' 'skill-plan' 'skip':88 'slice':250,264,271 'solv':149,214 'sourc':221,232 'source-jhostalek' 'specif':310,465,650 'specifi':397,407 'src/api/app.py':444 'src/api/middleware/auth.py':438 'src/api/middleware/ratelimit.py':433 'src/infra/redis.py':452 'stage':284 'start':40,458 'status':418 'step':9,369,476,508,509,522,618,639,667 'still':122 'stop':104,138 'strategi':258 'subag':167 'summari':170 'surfac':319,331,504 'surpris':269 'surviv':642 'switch':251 'tabl':559 'task':5,25,243,254,538 'tbd':643 'term':552 'test':454 'topic-agent-skills' 'topic-ai-coding' 'topic-anthropic' 'topic-claude' 'topic-claude-code' 'topic-claude-code-skills' 'topic-code-review' 'topic-codex-cli' 'topic-cursor' 'topic-developer-tools' 'topic-git-workflow' 'topic-multi-agent' 'touch':518 'tradeoff':113 'two':159 'type':686 'uncertain':279 'under-specifi':395 'understood':600 'updat':692 'url':233 'use':2,446 'user':377,424,660 'valu':554 'variabl':415 've':131,146 'vendor':217 'verif':519 'vertic':249,263 'via':163 'vs':622 'walk':277 'warrant':539 'web':209 'window':45 'wire':290 'without':196,471,649 'work':303,613,721 'would':370 'write':106 'wrong':37,59,461 'zone':300","prices":[{"id":"a3212e61-4a80-496c-8e10-f845eeb9f3e9","listingId":"29423fe9-906f-48ff-b512-39f9354c378a","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"JHostalek","category":"dotclaude","install_from":"skills.sh"},"createdAt":"2026-05-18T13:20:33.542Z"}],"sources":[{"listingId":"29423fe9-906f-48ff-b512-39f9354c378a","source":"github","sourceId":"JHostalek/dotclaude/plan","sourceUrl":"https://github.com/JHostalek/dotclaude/tree/main/skills/plan","isPrimary":false,"firstSeenAt":"2026-05-18T13:20:33.542Z","lastSeenAt":"2026-05-18T19:13:16.505Z"}],"details":{"listingId":"29423fe9-906f-48ff-b512-39f9354c378a","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"JHostalek","slug":"plan","github":{"repo":"JHostalek/dotclaude","stars":8,"topics":["agent-skills","ai-coding","anthropic","claude","claude-code","claude-code-skills","code-review","codex-cli","cursor","developer-tools","git-workflow","multi-agent","prompt-engineering","skill-md"],"license":"cc0-1.0","html_url":"https://github.com/JHostalek/dotclaude","pushed_at":"2026-05-17T15:07:41Z","description":"Agent skills for agentic coding tools. Extremely opinionated. Updated (almost) daily.","skill_md_sha":"035c78b867909cd56181f5045b5d29c79e5690d6","skill_md_path":"skills/plan/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/JHostalek/dotclaude/tree/main/skills/plan"},"layout":"multi","source":"github","category":"dotclaude","frontmatter":{"name":"plan","description":"Use when a task is multi-step, ambiguous, or high-impact and you need an executable implementation plan before editing code."},"skills_sh_url":"https://skills.sh/JHostalek/dotclaude/plan"},"updatedAt":"2026-05-18T19:13:16.505Z"}}