Goal Driven Decomposition

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 — propose/apply/archive 三阶段把 change 沉淀成 specs. 本 skill 区别: OpenSpec 围绕已有项目的 spec 演进; 本 skill 在 spec 之前先 gate truegoal (1-layer-deeper proposal under USER GATE) + persona reaction, 防止 spec 跑偏.
• 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).

1. 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.

1. 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).
2. **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
• Source: tranfu-labs/tranfu-skills
• License: MIT

Install and usage instructions live in the source repository linked above.