# Goal Driven Decomposition > >- - **Type:** Skill - **Install:** `agentstack add skill-tranfu-labs-tranfu-skills-goal-driven-decomposition` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [tranfu-labs](https://agentstack.voostack.com/s/tranfu-labs) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [tranfu-labs](https://github.com/tranfu-labs) - **Source:** https://github.com/tranfu-labs/tranfu-skills/tree/main/own-skills/goal-driven-decomposition ## Install ```sh agentstack add skill-tranfu-labs-tranfu-skills-goal-driven-decomposition ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Goal-Driven Decomposition > **Citation convention used in this skill** > Inline references look like `[Author Year, §section]` or `[Source]`. They sit next to the specific claim they support, not at the end. The full reference list is in the **References** section at the bottom. Claims without a citation are either common knowledge or distilled from this skill's own iteration history (a real conversation in which an LLM repeatedly over-engineered a "Monte Carlo simulation website" request before being corrected — that conversation is the seed case for this skill, recorded in the Appendix). ## What this skill exists for LLMs systematically over-engineer when given short goals. Given "build a Monte Carlo simulation website" the default failure mode is to immediately produce a Kubernetes-grade architecture (Redis Streams, worker pools, Rust modules) instead of recognizing that "website" + "simulation" + casual phrasing implies a teaching demo that should run entirely in the browser. *(This is the seed case — see the Appendix at the end for the full failure trace.)* This is a known failure pattern in the literature, called **premature decomposition** or **overengineering**: - **Decomposition has a hidden coordination cost.** Amazon Science formalized this as `O(n) + O(k^m)` where `k` is the number of subtasks and `1 由 tranfu-publish 起草, 作者签字. 帮助阅读者横向决定要装哪个 / 跳到更合适的同类. ### 公司库内 - [write-spec](../write-spec/SKILL.md) — 从模糊想法一次性出 PRD/feature spec (目标 / 用户故事 / 验收标准). **本 skill 区别**: write-spec 是单轮 spec 生成, 输出即结束; 本 skill 是多轮 doc-relay (persona-brief → design-draft → persona-reaction → final) + ≤3 iter validation-fix 闭环, 跑到真产物为止. - [structured-thinking-advisor](../structured-thinking-advisor/SKILL.md) — 对已有文档/思路给 2-3 个维度的优化版本. **本 skill 区别**: STA 是横向审视已有产物; 本 skill 是从 "做一个 X" 的空白 goal 起, 跑完整 cold-start → 拆维 → 建产物. - [business-analysis-pipeline](../business-analysis-pipeline/SKILL.md) — 7 步评估 AI 产品商业可行性. **本 skill 区别**: BAP 评估"该不该做"; 本 skill 在"决定要做"后驱动"怎么做到产物". ### 外部世界 - [openspec](https://github.com/Fission-AI/OpenSpec) — propose/apply/archive 三阶段把 change 沉淀成 specs. **本 skill 区别**: OpenSpec 围绕已有项目的 spec 演进; 本 skill 在 spec 之前先 gate true_goal (1-layer-deeper proposal under USER GATE) + persona reaction, 防止 spec 跑偏. - [superpowers](https://github.com/obra/superpowers) — 通用 agent workflow 工具集 (复杂编码任务). **本 skill 区别**: superpowers 是横向工具库; 本 skill 是纵向单一协议 — "build X" goal 到 artifact 的端到端 pipeline, 强制 sample-track blind-compare. ### 本 skill 独特价值 - enumerate vs sample 双轨, 视觉/排版/文案 走必 render PNG + 盲选 anti-ref 校验. - persona 是协同设计者, 非纯反馈者; 借 fresh Agent + @mention'd .md 防 SendMessage 漂移. - 维度级 ≤3 iter validation-fix 闭环, 跑不通强制 surface 给用户, 不静默放过. ## 使用技巧 > 由 tranfu-publish 引导起草. 帮助阅读者纵向上手 — tacit knowledge 在此. ### 材料方案 - 干净 goal-docs/ 空目录起步; 已有目录会走 iteration mode, 不要混. - persona "审美参考" 必须配 goal-docs/_refs/ 下的本地截图, 不能只给产品名. - sample-track 维度准备 1-3 张 hero-ref + 1-3 张 anti-ref 截图 (用于 blind-compare). ### 推荐用法 - 第一次跑: 一句 "做一个 X" 直接触发, 不要预先列需求, 让 skill 先 prior-weight. - 改已有项目: 说 "X 偏了改一下" / "加 Y", 走 iteration mode, scope Agent 会分类. - sample-track 维度卡住: 看 90-validation-plan-r{N}.md 的 critical blind-compare 是否覆盖. ### 已知限制 - 大: SKILL.md 121K + HISTORY.md 40K, context 占用高, 短任务不要装. - 不接 pure one-shot (零设计维度, e.g. "改个 typo"), 自带跳出条款. - ≤3 iter 后必须 surface 给用户, 不会无限自循环, 适合人在环里. ## Tracks: enumerate vs sample Dimensions are not uniform. They split into two tracks based on the *compressibility* of their spec: - **enumerate-track** — spec compresses losslessly into a finite set of discrete text decisions. Verifying compliance = checking each decision is in place. Examples: feature lists, stack choices, deployment config, data schemas, scheduling. - **sample-track** — spec is continuous, globally-experiential, and *cannot* be losslessly encoded in text. Atomic property checks (`borderRadius == 6px ∧ surface tier ≥ 2 ∧ font !== Inter ∧ ...`) are *consequences* of "looks shadcn" — they never test the gestalt itself. Examples: UI 风格, 视觉, 排版, 文案 tone, 品牌调性, 节奏感. This is an **epistemic** distinction, not a stylistic one. Functional/technical specs survive a text relay (brief → design → impl → check) intact, because each step's text faithfully encodes its predecessor's decisions. Visual/experiential specs do not survive — every text encoding step strips holistic information that the next decoder cannot reconstruct, and atomic property checks measure the *projections* of the spec, never the spec itself. **Failure mode that motivated this split** (tranfu-site r1→r3): three full doc-relay rounds ran enumerate-track protocol on the UI dim. r3's plan had 51 atomic checks (49/51 pass) — yet the rendered home page kept `[全部][踩坑][养成]` plain bracket text and felt 1999, because no round ever produced a visual sample for the persona to react to. The text relay was internally consistent and visually wrong. *(See HISTORY.md Appendix G.)* **Default classification by spec form**: | If the dim's spec is mostly… | Track | |---|---| | feature presence/absence, branching/loops, scheduling, data shape, infra config | enumerate | | visual gestalt, typography rhythm, copy tone, pacing, brand feel | sample | The protocol below routes each dim through the matching track. Sections marked **2-E / 2-S** or **3-E / 3-S** are track-specific and you MUST take the right branch — operational details on labeling are in **Step 1.6**. ## The core algorithm ``` NOTE: pseudocode numbers are sequential for readability; section headings below are non-sequential (Step 6 missing is 7th-iter legacy). Each pseudo step carries a [→ §Step X] marker mapping to its section heading below. 0. [→ §Step 0] Detect mode: cold-start (no goal-docs/) vs iteration (goal-docs/ + persona exists) — if iteration → Step 0a (read state + classify request + scope Agent — now also identifies which goal-tree slice the request affects AND whether true_goal interpretation should be re-proposed); jump to the right downstream step (新增 → Step 2 on affected dims of affected slice; 修正 → Step 3; 画像变更 → surface; true_goal shift → Step 1.b under USER GATE) 1. [→ §Step 1] Receive goal. Two substeps: 1.a) Prior-weight: pick modal shape, intent, AND target user — DO NOT ASK. 1.b) [→ §Step 1.b] Propose 1-layer-deeper interpretation under USER GATE. Format: "字面 X / 底层 Y / 建议调整为 Z / why". HARD CAP = 1 layer. Skip if no signal (don't fabricate). Output: - user_goal_surface.md (★ 字面原话, 只读, 审计镜) - 00-true-goal-r{N}.md (★ ground truth — surface verbatim if user rejected proposal or it was skipped; the proposed underlying reinterpretation if user accepted) All downstream steps anchor on 00-true-goal, NOT user_goal_surface. 2. [→ §Step 1.5] Instantiate the target user as a concrete, roleplay-able persona (00-用户画像-r{N}.md — must be specifiable in writing, not just labels; 审美参考 split into hero-refs / anti-refs, each with a local screenshot path under goal-docs/_refs/) 2.5. [→ §Step 1.6] Label each stable dim's TRACK (see § Tracks above): - enumerate-track: spec is text-decomposable (功能 / 技术 / 部署 / 数据模型 / 调度) - sample-track: spec is continuous-holistic (UI / 视觉 / 排版 / 文案 tone / 品牌调性) Track choice routes the dim through Step 2-E vs Step 2-S, and Phase 3a-E vs 3a-S. 2.7. [→ §Step 1.7] Spawn fresh Agents for DoD + Goal Tree: - DoD-Agent → 10-DoD-r{N}.md (observable success criteria, agreed with persona Agent) - GoalTree-Agent → 20-goal-tree-r{N}.md (北极星 → Phase → slice; each slice carries a verifiable milestone artifact + DoD subset) - First slice MUST be thinnest end-to-end path that touches all dims (not all of dim A first → all of dim B). Slice 1 = end-to-end thin slice always. Main agent does NOT write these docs itself; spawn fresh Agents per Step 1.7.a/b. ----- per-slice loop (repeats per slice from goal tree) ----- 3. [→ §Step 2] For each dim in slice, run track-appropriate doc-relay: • Step 2-E (enumerate): persona brief → design draft (text) → persona-reaction (async, sonnet, MANDATORY) → [if pushback] design final • Step 2-S (sample): persona brief → design draft outputs 1-3 candidate PNGs FIRST → design.md → persona-reaction MUST view PNGs → [if pushback] design final re-renders a PNG (text-only patch forbidden) All Agents are fresh; persistence lives in @mention'd docs (and PNGs), not chat. 4. [→ §Step 2.5] Role-anchored build-plan Agent, per dim. Same role across (a)-(d). Role prompt MUST name reverse priors (e.g. "10年 shadcn/Vercel 学派 UI 设计师, 反 1999 PG-essays 裸 HTML"). Holds {user_goal_surface, true_goal, persona, design-final, hero/anti-refs, repo_state}. (a) align-check (sync, sonnet) — answer ONLY "design 服务 true_goal? ≤3 misalignment OR OK". Misalign → bounce to Step 3 (regenerate design). (b) translate (sync, sonnet) → 40-build-plan-{dim}-r{N}.md with hard constraints: - explicit tokens / primitives / scale (no vibes words) - every decision traced to a sentence in design.md / true_goal - §implicit-decisions section MANDATORY: every judgment design.md left underspecified, with 2 candidates + which chosen + why (c) plan-react (sample-track only, async sonnet, run_in_background=true) — persona reads plan, judges per-token "more like hero-ref or anti-ref?". Pushback → return to (b). (d) hero-only early render (recommended for sample-track) — render most prominent component (hero / 首屏 card) per the plan; run a subset of Step 5 blind-compare. Fail → return to (b). Pulls cheapest validation forward of build. 5. Build the slice (code/site/etc.) according to design docs + build-plan. 6. [→ §Step 3] Validation-fix loop on the slice's built artifact (same as before): plan Agent → 90-validation-plan-r{N}.md (every check traced; severity = critical|nice; sample-track dims MUST contain ≥1 critical blind-compare; atomic checks on sample-track = anti-trope guardrails, necessary not sufficient) for iter in 1..3: validation Agent → 91-validation-run-r{N}-{iter}.md (any tools) if all CRITICAL pass → exit success fix Agent → modifies code + writes 92-fix-attempt-r{N}-{iter}.md if iter == 3 and still failing → surface to user. 7. [→ §Step 3.5] Milestone gate (after slice's validation passes). Three questions plus a surface-mirror check, written to a short doc in goal-docs/ (or appended to the round's STATE.md): ① slice's milestone artifact really done per 20-goal-tree? ② still serves true_goal? ③ does this finding require re-pruning subsequent slices? Plus a SURFACE-MIRROR CHECK: would a literal reader of user_goal_surface.md recognize what was built as "what they asked for"? Mirror failure = AI overreach; bounce to Step 1.b to surface the divergence to user. NO → update 20-goal-tree-r{N+1}, restart the slice (or change slice plan). YES → continue. 8. [→ §Step 3.7] Acceptance walkthrough. Persona Agent walks through the REAL built artifact (live UI, real CLI — NOT mocks, NOT screenshots). Subjective feedback flows back into 00-用户画像-r{N+1}.md hero/anti-refs immediately, not deferred to project end. 9. More slices in goal tree? → return to Step 3 with next slice. All slices done? → continue to Step 7 (retro). ----- end per-slice loop ----- 10. [→ §Step 7] Project-end retro → 99-retro-r{N}.md. Capture: where did we drift, why did we drift, what should the prior have been? Diffs flow back into 00-用户画像-r{N+1}.md §审美参考 (especially anti-refs). Closes the only project-to-project feedback loop the protocol has. 11. [→ §Step 5] If user pushes back on docs or final artifact → update posterior, regenerate. 12. [→ §Step 4] Decompose deeper only when a dimension cannot settle, or user explicitly asks. ``` The key inversion vs. naive planning: **don't expand the goal tree until forced to**. The first response is a committed answer at the leaf, not a survey of branches. *(This is the same recursion-on-failure structure as ADaPT, but applied at the design level rather than the action level. `[Prasad et al. 2024, §3]`)* But "leaf" doesn't mean "one sentence." For most build-something goals, the leaf is a small set of **stable dimensions** of that entity type (a website has 功能/UI/技术选型/部署; a CLI tool has 命令/IO/配置/分发). And each cell of that leaf isn't filled by the main agent in one stroke — it's filled by a **persona ↔ design dialogue mediated by docs**, because in-conversation alignment is too easy to fake. Fresh-context Agents communicating through artifacts is what makes "反复对齐" a physical process, not a stylistic claim. ## Step 0 — Cold-start vs iteration mode Before any prior weighting, check whether `goal-docs/` already exists in the user-mentioned project (or in cwd if no project named) AND contains at least `00-用户画像-r{N}.md` for some N. **Cold-start** (no `goal-docs/` or no persona doc): proceed to Step 1. **Iteration mode** (existing `goal-docs/` with persona): the work has been started before; do NOT re-derive prior weighting, do NOT regenerate the persona, do NOT re-run all dimensions. Instead: 1. **Read state** — main agent reads `00-r{latest}-用户画像.md` + `STATE.md` (if it exists, gives current per-dim latest round) + `CHANGELOG.md` + the latest design doc per dimension. 2. **Classify the user's request** silently from cues: - **新增 (additive)** — "加 X / 也支持 Y / 还要做 Z / 增加 W". Extends scope without contradicting prior decisions. - **修正 (corrective)** — "X 不对 / 改成 Y / X 偏了 / Z 应该是 W / 现在的问题是…". Reports a mismatch between built artifact and design intent (or design vs persona). - **画像变更 (foundational)** — "目标用户改成 X / 受众增加 Y / 这次面向 Z". Invalidates the persona's premises. **Do NOT auto-execute this branch — surface to user (see below).** 3. **Spawn scope Agent** (sync, default model, fresh context). Inputs: persona + latest design docs + `CHANGELOG.md` + the user's verbatim request. Output: `goal-docs/UPDATE-r{N+1}-scope.md` listing: - request type (新增 / 修正 / 画像变更) - affected dimensions (module IDs) + rationale per - **track per affected dim** (enumerate / sample); flag any **track-change** vs prev round (enumerate↔sample switch = major redesign — text tokens largely deprecated, samples must be drawn or redrawn from scratch) - **affected slice(s)** in `20-goal-tree-r{N}.md` *(8th iter / Appendix H)* — milestone artifact's owner. E.g. "修正 [全部][踩坑][养成] brackets" is "slice = 首页, dim = UI"; without the slice tag, the fix loop patches in isolation without re-checking the slice's milestone artifact. If the request affects a future slice not yet built, mark `slice = pending` and queue the change against that slice's eventual `40-build-plan` rather than running fix loop now. - **true_goal recheck** *(8th iter / Appendix H)* — does the user's request imply the underlying goal has shifted? If yes, surface a new Step 1.b proposal under USER GATE (write `00-true-goal-r{N+1}.md` only after user approves) before executing 新增 / 修正. If no, all downstream steps continue anchoring on the existing `00-true-goal-r{N}.md`. The scope Agent does NOT auto-rewrite true_goal — same authority rule as 画像变更. - whether validation needs new checks (and what they roughly are; sample-track dims must list at least one new blind-compare check if hero/anti refs have changed) - which prior `0X-r*-design-*.md` files (and any `_samples/*.png`) are superseded vs extended The scope Agent does NOT design solutions; it scopes the work. Main agent reads its output and proceeds. 4. **Append to CHANGELOG.md** — one entry per round with: trigger (user's exact request), type, scope (affected modules), eventual outcome (filled in after validation closes). 5. **Execute by … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [tranfu-labs](https://github.com/tranfu-labs) - **Source:** [tranfu-labs/tranfu-skills](https://github.com/tranfu-labs/tranfu-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-tranfu-labs-tranfu-skills-goal-driven-decomposition - Seller: https://agentstack.voostack.com/s/tranfu-labs - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.