Docs: clarify kanban fan-out decomposition

Fixes on record

Merged to main. A stamp counts the issues a fix is linked to.

• #22939 docs(skills): clarify kanban fan-out decomposition (salvage #22898)

  merged to main

  files: scripts/release.py, skills/devops/kanban-orchestrator/SKILL.md

  Show the diff

  • scripts/release.py

    @@ -841,6 +841,7 @@
         "[redacted:email]": "0xharryriddle",
         "[redacted:email]": "lhysdl",
         "[redacted:email]": "SherlockShemol",
    +    "[redacted:email]": "eloklam",
         "[redacted:email]": "fmercurio",
         "[redacted:email]": "Ricardo-M-L",
         "[redacted:email]": "leozeli",

  • skills/devops/kanban-orchestrator/SKILL.md

    @@ -32,6 +32,8 @@ Your job description says "route, don't execute." The rules that enforce that:
     
     - **Do not execute the work yourself.** Your restricted toolset usually doesn't even include terminal/file/code/web for implementation. If you find yourself "just fixing this quickly" — stop and create a task for the right specialist.
     - **For any concrete task, create a Kanban task and assign it.** Every single time.
    +- **Split multi-lane requests before creating cards.** A user prompt can contain several independent workstreams. Extract those lanes first, then create one card per lane instead of bundling unrelated work into a single implementer card.
    +- **Run independent lanes in parallel.** If two cards do not need each other's output, leave them unlinked so the dispatcher can fan them out. Link only true data dependencies.
     - **If no specialist fits, ask the user which profile to create.** Do not default to doing it yourself under "close enough."
     - **Decompose, route, and summarize — that's the whole job.**
     
    @@ -58,7 +60,24 @@ Ask clarifying questions if the goal is ambiguous. Cheap to ask; expensive to sp
     
     ### Step 2 — Sketch the task graph
     
    -Before creating anything, draft the graph out loud (in your response to the user). Example for "Analyze whether we should migrate to Postgres":
    +Before creating anything, draft the graph out loud (in your response to the user). Treat every concrete workstream as a candidate card:
    +
    +1. Extract the lanes from the request.
    +2. Assign each lane to the best specialist.
    +3. Decide whether each lane is independent or gated by another lane.
    +4. Create independent lanes as parallel cards with no parent links.
    +5. Create synthesis/review/integration cards with parent links to the lanes they depend on.
    +
    +Examples of prompts that should fan out:
    +
    +- "Build an app" -> `designer` for product/UI direction and `frontend-eng` or `backend-eng` for implementation, with a later integration/review card if needed.
    +- "Fix blockers and check model variants" -> one implementation card for the blocker fixes plus one discovery/research card for config/source verification. A final reviewer card can depend on both.
    +- "Research docs and implement" -> a docs-research card can run in parallel with a codebase-discovery card; implementation waits only if it truly needs those findings.
    +- "Analyze this screenshot and find the related code" -> `observer` handles visual analysis while an explorer-style profile searches the codebase.
    +
    +Words like "also," "finally," or "and" do not automatically imply a dependency. They often mean "make sure this is covered before reporting back." Only link tasks when one card cannot start until another card's output exists.
    +
    +Example for "Analyze whether we should migrate to Postgres":
     
     ```
     T1  researcher        research: Postgres cost vs current
    @@ -136,6 +155,8 @@ Tell them what you created in plain prose:
     
     **Fan-out + fan-in (research → synthesize):** N `researcher` tasks with no parents, one `analyst` task with all of them as parents.
     
    +**Parallel implementation + validation:** one implementer card makes the change while one explorer/researcher card verifies config, docs, or source mapping. A reviewer card can depend on both. Do not make the implementer own unrelated verification just because the user mentioned both in one sentence.
    +
     **Pipeline with gates:** `pm → backend-eng → reviewer`. Each stage's `parents=[previous_task]`. Reviewer blocks or completes; if reviewer blocks, the operator unblocks with feedback and respawns.
     
     **Same-profile queue:** 50 tasks, all assigned to `translator`, no dependencies between them. Dispatcher serializes — translator processes them in priority order, accumulating experience in their own memory.
    @@ -144,6 +165,12 @@ Tell them what you created in plain prose:
     
     ## Pitfalls
     
    +**Bundling independent lanes into one card.** If the user asks for two independent outcomes, create two cards. Example: "fix blockers and check model variants" is not one fixer task; create a fixer/engineer card for the fixes and an explorer/researcher card for the variant check, then optionally gate review on both.
    +
    +**Over-linking because of wording.** "Finally check X" may still be parallel with implementation if X is static config, docs, or source discovery. Link it after implementation only when the check depends on the implementation result.
    +
    +**Forgetting dependency links.** If the task graph says `research -> implement -> review`, do not create all tasks as independent ready cards. Use parent links so implement/review cannot run before their inputs exist.
    +
     **Reassignment vs. new task.** If a reviewer blocks with "needs changes," create a NEW task linked from the reviewer's task — don't re-run the same task with a stern look. The new task is assigned to the original implementer profile.
     
     **Argument order for links.** `kanban_link(parent_id=..., child_id=...)` — parent first. Mixing them up demotes the wrong task to `todo`.