{"id":"700b0b6b-7e24-48e6-8d4a-28ac79cd8657","shortId":"g9hfNZ","kind":"skill","title":"refine-plan","tagline":"Iteratively review and revise a planning artifact until no new findings survive evaluation. Supports plans, shells, and specs. Use when the user asks to \"refine the plan\", \"refine the shells\", \"refine this spec\", \"iterate on the plan\", \"iterate on the shells\", \"tighten the plan\",","description":"# Refine Plan\n\nLoop the review pipeline over a planning artifact until no new findings are accepted. Writes back to the artifact file(s) in place. Supports plans, shells, and specs.\n\n## Task Tracking\n\nAt the start of every invocation (including re-runs from Step 5), use `TaskCreate` to create a task for each step:\n\n1. Resolve the artifact\n2. Run `/review-plan` skill\n3. Run `/evaluate-findings` skill\n4. Run `/apply-findings` skill\n5. Re-run `/refine-plan` skill if changed\n\n## Step 1: Resolve the Artifact\n\n### Determine Artifact Type\n\n1. **Explicit argument** — If the user specified a type (e.g., \"refine plan\", \"refine shells\", \"refine spec\"), use it\n2. **Conversation context** — Infer from conversation (e.g., if `/draft-plan` just ran, type is plan)\n3. **Auto-detect** — Check `.turbo/` for existing artifacts. If multiple types exist, use `AskUserQuestion`\n\n### Resolve the Artifact File(s)\n\n#### Plan\n\n1. **Explicit path** — use it\n2. **Explicit slug** — resolve to `.turbo/plans/<slug>.md`\n3. **Single file** — Glob `.turbo/plans/*.md`. If exactly one file exists, use it\n4. **Most recent** — most recently modified file\n5. **Legacy fallback** — `.turbo/plan.md` if `.turbo/plans/` does not exist\n6. **Nothing found** — tell the user to run `/turboplan` (for a new task) or `/pick-next-shell` (for existing shells) and stop\n\n#### Shells\n\n1. **Explicit spec slug** — Glob `.turbo/shells/<slug>-*.md`\n2. **Explicit spec path** — derive slug from filename, glob as above\n3. **Single spec** — Glob `.turbo/specs/*.md`. If exactly one, derive slug and glob for shells\n4. **Most recent spec** — most recently modified spec, derive slug and glob\n5. **Nothing found** — tell the user to run `/draft-shells` first and stop\n\nFor shells, read each shell file and extract from its YAML frontmatter: `spec` (source spec path) and `depends_on`. Verify the source spec exists. State the spec path, number of shells, and each shell's filename.\n\n#### Spec\n\n1. **Explicit path** — use it\n2. **Explicit slug** — resolve to `.turbo/specs/<slug>.md`\n3. **Single file** — Glob `.turbo/specs/*.md`. If exactly one, use it\n4. **Most recent** — most recently modified\n5. **Legacy fallback** — `.turbo/spec.md` if `.turbo/specs/` does not exist\n6. **Nothing found** — tell the user to run `/draft-spec` first and stop\n\nIf multiple candidates exist and the choice is non-obvious, use `AskUserQuestion`.\n\nState the resolved path(s) before continuing.\n\n## Step 2: Run `/review-plan` Skill\n\nRun the `/review-plan` skill on the resolved artifact.\n\nAlways run this step even if the artifact looks polished.\n\n## Step 3: Run `/evaluate-findings` Skill\n\nRun the `/evaluate-findings` skill on the review findings from Step 2.\n\n## Step 4: Run `/apply-findings` Skill\n\nRun the `/apply-findings` skill on the evaluated results.\n\n## Step 5: Re-run `/refine-plan` Skill if Changed\n\nCheck whether the artifact file(s) were edited during Step 4. Any edit counts.\n\nThe iteration number below refers to the `/refine-plan` run currently executing Step 5. It is not the iteration number of a prospective re-run. Iteration 1 is the initial run; iteration 2 is the first auto-re-run; iteration 3 is the second auto-re-run; iteration 4 and beyond exist only when the user opts in at the hard-cap ask. Iterations 1 and 2 always follow the classification gate (they never trigger the hard cap at their own Step 5, even when the auto-re-run they spawn would be iteration 3). The hard cap fires at the end of iteration 3 and every iteration thereafter.\n\n**Iterations 1 and 2, if changes were made**, classify what Step 4 edited:\n\n- **Structural edits** — run `/refine-plan` again via the Skill tool, passing the artifact type and resolved path. If the round contains both structural and prose-only edits, treat it as structural and re-run automatically.\n- **Prose-only edits only** (reworded sentences in place, fixed stale examples, clarified existing text without changing meaning) — output a summary of what changed, then use `AskUserQuestion` to ask whether to run one more round or stop here. Do not silently continue or silently stop.\n\n**Iterations 1 and 2, if changes were made but you believe re-running is unnecessary**, use `AskUserQuestion` to ask for skip permission. Do not skip silently.\n\n**Iteration 3 or later, if Step 4 of this run made changes**, the hard cap is reached. This replaces the classification gate above for iteration 3 and every iteration after it. Output a summary of what is still changing and whether it is structural or prose-only. Then use `AskUserQuestion` to offer three options: continue for another iteration, stop here and accept the artifact as-is, or escalate to `/consult-oracle` for a different perspective on the remaining issues.\n\nThe re-invocation is a full, fresh run of this skill. Every step (1-5) executes with its own task tracking and skill invocations.\n\nThen use the TaskList tool and proceed to any remaining task.\n\n### Structural Edit Examples by Type\n\n- **Plan** — added or removed steps, new or removed design decisions, rewired dependencies between steps, changed testing strategy\n- **Shells** — added or removed shells, changed Produces/Consumes/Covers Spec Requirements wiring, changed frontmatter `depends_on`, added or removed spec requirement coverage\n- **Spec** — added or removed sections, new or removed requirements, rewired cross-references, changed acceptance criteria\n\n## Rules\n\n- Every step must run in every iteration. `/evaluate-findings` is a judgment gate that must run before `/apply-findings` touches the artifact. Each step must invoke its designated skill via the Skill tool.\n- Re-invocations from Step 5 are full runs with fresh task tracking and complete skill invocations.\n- The artifact file(s) are the only files that should change. For shells, do not modify the source spec.","tags":["refine","plan","turbo","tobihagemann","agent-skills","claude-code","claude-skills","developer-tools","skills"],"capabilities":["skill","source-tobihagemann","skill-refine-plan","topic-agent-skills","topic-claude-code","topic-claude-skills","topic-developer-tools","topic-skills"],"categories":["turbo"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/tobihagemann/turbo/refine-plan","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add tobihagemann/turbo","source_repo":"https://github.com/tobihagemann/turbo","install_from":"skills.sh"}},"qualityScore":"0.590","qualityRationale":"deterministic score 0.59 from registry signals: · indexed on github topic:agent-skills · 280 github stars · SKILL.md body (5,819 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-04-22T00:54:11.168Z","embedding":null,"createdAt":"2026-04-18T22:03:58.625Z","updatedAt":"2026-04-22T00:54:11.168Z","lastSeenAt":"2026-04-22T00:54:11.168Z","tsv":"'-5':817 '/apply-findings':116,455,459,913 '/consult-oracle':793 '/draft-plan':160 '/draft-shells':302 '/draft-spec':389 '/evaluate-findings':112,439,443,904 '/pick-next-shell':242 '/refine-plan':122,470,495,617 '/review-plan':108,416,420 '/turboplan':236 '1':102,127,134,187,249,343,514,555,602,696,816 '2':106,152,192,256,348,414,451,520,557,604,698 '3':110,166,199,267,355,437,529,586,596,723,747 '4':114,212,282,366,453,484,538,612,728 '5':92,118,219,294,372,466,500,573,933 '6':228,381 'accept':63,784,894 'ad':844,861,874,881 'alway':426,558 'anoth':779 'argument':136 'artifact':10,57,68,105,130,132,174,183,425,433,477,625,786,916,946 'as-i':787 'ask':26,553,678,714 'askuserquest':180,405,676,712,772 'auto':168,525,534,578 'auto-detect':167 'auto-re-run':524,533,577 'automat':649 'back':65 'believ':705 'beyond':540 'candid':395 'cap':552,568,589,736 'chang':125,473,606,666,673,700,733,760,857,865,870,893,955 'check':170,474 'choic':399 'clarifi':662 'classif':561,742 'classifi':609 'complet':942 'contain':633 'context':154 'continu':412,691,777 'convers':153,157 'count':487 'coverag':879 'creat':96 'criteria':895 'cross':891 'cross-refer':890 'current':497 'decis':852 'depend':323,854,872 'deriv':260,276,290 'design':851,922 'detect':169 'determin':131 'differ':796 'e.g':143,158 'edit':481,486,613,615,640,653,839 'end':593 'escal':791 'evalu':16,463 'even':430,574 'everi':84,598,749,814,897,902 'exact':206,274,362 'exampl':661,840 'execut':498,818 'exist':173,178,209,227,244,329,380,396,541,663 'explicit':135,188,193,250,257,344,349 'extract':313 'fallback':221,374 'file':69,184,201,208,218,311,357,478,947,952 'filenam':263,341 'find':14,61,448 'fire':590 'first':303,390,523 'fix':659 'follow':559 'found':230,296,383 'fresh':809,938 'frontmatt':317,871 'full':808,935 'gate':562,743,908 'glob':202,253,264,270,279,293,358 'hard':551,567,588,735 'hard-cap':550 'includ':86 'infer':155 'initi':517 'invoc':85,805,826,930,944 'invok':920 'issu':801 'iter':4,37,41,489,505,513,519,528,537,554,585,595,599,601,695,722,746,750,780,903 'judgment':907 'later':725 'legaci':220,373 'look':434 'loop':50 'made':608,702,732 'md':198,204,255,272,354,360 'mean':667 'modifi':217,288,371,960 'multipl':176,394 'must':899,910,919 'never':564 'new':13,60,239,848,885 'non':402 'non-obvi':401 'noth':229,295,382 'number':334,490,506 'obvious':403 'offer':774 'one':207,275,363,682 'opt':546 'option':776 'output':668,753 'pass':623 'path':189,259,321,333,345,409,629 'permiss':717 'perspect':797 'pipelin':53 'place':72,658 'plan':3,9,18,30,40,47,49,56,74,145,165,186,843 'polish':435 'proceed':833 'produces/consumes/covers':866 'prose':638,651,768 'prose-on':637,650,767 'prospect':509 'ran':162 're':88,120,468,511,526,535,579,647,707,804,929 're-invoc':803,928 're-run':87,119,467,510,646,706 'reach':738 'read':308 'recent':214,216,284,287,368,370 'refer':492,892 'refin':2,28,31,34,48,144,146,148 'refine-plan':1 'remain':800,836 'remov':846,850,863,876,883,887 'replac':740 'requir':868,878,888 'resolv':103,128,181,195,351,408,424,628 'result':464 'review':5,52,447 'revis':7 'rewir':853,889 'reword':655 'round':632,684 'rule':896 'run':89,107,111,115,121,235,301,388,415,418,427,438,441,454,457,469,496,512,518,527,536,580,616,648,681,708,731,810,900,911,936 'second':532 'section':884 'sentenc':656 'shell':19,33,44,75,147,245,248,281,307,310,336,339,860,864,957 'silent':690,693,721 'singl':200,268,356 'skill':109,113,117,123,417,421,440,444,456,460,471,621,813,825,923,926,943 'skill-refine-plan' 'skip':716,720 'slug':194,252,261,277,291,350 'sourc':319,327,962 'source-tobihagemann' 'spawn':582 'spec':21,36,77,149,251,258,269,285,289,318,320,328,332,342,867,877,880,963 'specifi':140 'stale':660 'start':82 'state':330,406 'step':91,101,126,413,429,436,450,452,465,483,499,572,611,727,815,847,856,898,918,932 'still':759 'stop':247,305,392,686,694,781 'strategi':859 'structur':614,635,644,765,838 'summari':670,755 'support':17,73 'surviv':15 'task':78,98,240,822,837,939 'taskcreat':94 'tasklist':830 'tell':231,297,384 'test':858 'text':664 'thereaft':600 'three':775 'tighten':45 'tool':622,831,927 'topic-agent-skills' 'topic-claude-code' 'topic-claude-skills' 'topic-developer-tools' 'topic-skills' 'touch':914 'track':79,823,940 'treat':641 'trigger':565 'turbo':171 'turbo/plan.md':222 'turbo/plans':197,203,224 'turbo/shells':254 'turbo/spec.md':375 'turbo/specs':271,353,359,377 'type':133,142,163,177,626,842 'unnecessari':710 'use':22,93,150,179,190,210,346,364,404,675,711,771,828 'user':25,139,233,299,386,545 'verifi':325 'via':619,924 'whether':475,679,762 'wire':869 'without':665 'would':583 'write':64 'yaml':316","prices":[{"id":"ec4d3f3f-5552-476a-a28e-86fa0d077cc5","listingId":"700b0b6b-7e24-48e6-8d4a-28ac79cd8657","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"tobihagemann","category":"turbo","install_from":"skills.sh"},"createdAt":"2026-04-18T22:03:58.625Z"}],"sources":[{"listingId":"700b0b6b-7e24-48e6-8d4a-28ac79cd8657","source":"github","sourceId":"tobihagemann/turbo/refine-plan","sourceUrl":"https://github.com/tobihagemann/turbo/tree/main/skills/refine-plan","isPrimary":false,"firstSeenAt":"2026-04-18T22:03:58.625Z","lastSeenAt":"2026-04-22T00:54:11.168Z"}],"details":{"listingId":"700b0b6b-7e24-48e6-8d4a-28ac79cd8657","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"tobihagemann","slug":"refine-plan","github":{"repo":"tobihagemann/turbo","stars":280,"topics":["agent-skills","claude-code","claude-skills","developer-tools","skills"],"license":"mit","html_url":"https://github.com/tobihagemann/turbo","pushed_at":"2026-04-21T12:22:12Z","description":"A composable dev process for Claude Code, packaged as modular skills.","skill_md_sha":"d616108ea740f0a8b1642f268a16d358b62a7db7","skill_md_path":"skills/refine-plan/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/tobihagemann/turbo/tree/main/skills/refine-plan"},"layout":"multi","source":"github","category":"turbo","frontmatter":{"name":"refine-plan","description":"Iteratively review and revise a planning artifact until no new findings survive evaluation. Supports plans, shells, and specs. Use when the user asks to \"refine the plan\", \"refine the shells\", \"refine this spec\", \"iterate on the plan\", \"iterate on the shells\", \"tighten the plan\", \"tighten the shells\", \"tighten the spec\", \"improve the plan\", \"improve the shells\", or \"improve the spec\"."},"skills_sh_url":"https://skills.sh/tobihagemann/turbo/refine-plan"},"updatedAt":"2026-04-22T00:54:11.168Z"}}