diff --git a/packages/skills-catalog/catalog/bundled/paperclip-operations/task-planning/SKILL.md b/packages/skills-catalog/catalog/bundled/paperclip-operations/task-planning/SKILL.md index 5304322f94..ce682bd16d 100644 --- a/packages/skills-catalog/catalog/bundled/paperclip-operations/task-planning/SKILL.md +++ b/packages/skills-catalog/catalog/bundled/paperclip-operations/task-planning/SKILL.md @@ -73,7 +73,7 @@ Use the Paperclip API to write the plan document, then comment: - If approval is required: `POST /api/issues/{issueId}/interactions` with `kind: request_confirmation`, `targetRevisionId` set to the new plan revision, `continuationPolicy: wake_assignee`, and `idempotencyKey: "confirmation:{issueId}:plan:{revisionId}"`. - Set the issue to `in_review` after creating the confirmation. Stay assigned so the acceptance wakes the planner. -When the plan is accepted, see the companion skill for converting accepted plans into Paperclip executable tasks. +When the plan is accepted, see the companion skill for converting accepted plans into Paperclip executable tasks. Key requirements covered there: produce a compact task matrix (task, owner, initial status, blockers); encode every hard dependency as `blockedByIssueIds` — parent/child nesting alone does not block execution; and verify the created issue graph before closing the source planning issue. ## Anti-patterns diff --git a/skills/paperclip-converting-plans-to-tasks/SKILL.md b/skills/paperclip-converting-plans-to-tasks/SKILL.md index 6b95b4d166..64d846df39 100644 --- a/skills/paperclip-converting-plans-to-tasks/SKILL.md +++ b/skills/paperclip-converting-plans-to-tasks/SKILL.md @@ -22,16 +22,25 @@ For the **mechanics** of recording a plan (issue document with key `plan`, comme - **Know your team.** Before assigning anything, look up the company's agents and their specialties (reporting lines, role descriptions, prior work). Don't default work to yourself when a better-suited agent exists; don't assign to a name you haven't checked. - **Assign for specialty.** Hand each piece of work to the agent most relevant to it. If no one fits, call that out — a hire, a tool, an external dependency, a board decision — instead of papering over the gap. - **Take responsibility.** Specialty-matching cuts both ways: when _you_ are the best-suited agent for a piece of work, assign it to yourself instead of reflexively delegating. Don't hand off to avoid load. -- **Use the dependency tree.** Paperclip's executor automatically starts any assigned task with no open blockers. Express every concrete deliverable as an issue, and wire real blockers via `blockedByIssueIds` (not prose like "blocked by X"). When `done`, dependents auto-wake. +- **Use the dependency tree.** Paperclip's executor automatically starts any assigned task with no open blockers. Parent/child issue nesting is structure, not execution blocking. Express every concrete deliverable as an issue, and wire every hard dependency from the plan through `blockedByIssueIds` on the dependent issue (not prose like "blocked by X"). When a blocker reaches `done`, dependents auto-wake. - **Order, then parallelize.** Sequence work by real dependencies, not by personal preference. Independent branches of the graph should start in parallel. Unlike humans, most agents allow concurrent runs, so you can assign parallel work to the same agent. - **Enough is enough.** Plans exist to unblock execution, not replace it. If the next step is small and clear, just do it or allow the plan to stand on its own. Re-planning a plan, or splitting work that one agent could finish in the time it took to break it up, is procrastination — ship something. +## When converting an accepted plan into tasks + +Before or while creating tasks, write a compact task matrix with each planned task, owner, initial status, and blockers. Any task that can start immediately should say why it has no blockers; otherwise set it to `blocked` and include the prerequisite issue IDs in `blockedByIssueIds`. Do not rely on `parentId`, child ordering, phase labels, or prose to block execution. + +After creating the tasks, re-fetch the created issues or otherwise verify the issue graph before marking the source planning issue done. Confirm that each dependent task has the expected `blockedByIssueIds`, each independent task has an explicit "can start now" reason, and the parent/child hierarchy is only being used for traceability. If expected blockers are missing, report the mismatch and leave the planning issue in `in_review` or `blocked` until the task graph is corrected. + ## Quick checklist before you publish a plan - [ ] Enough detail that assignees can act without re-asking. - [ ] Every concrete deliverable is an issue (or named as a known follow-up). - [ ] Each issue has a deliberate, specialty-matched assignee — not the planner by default. - [ ] Each issue's real blockers are declared via `blockedByIssueIds`. +- [ ] A compact task matrix names planned task, owner, initial status, and blockers. +- [ ] Tasks without blockers have an explicit reason they can start immediately. +- [ ] Created issues were re-fetched or otherwise verified before closing the source planning issue. - [ ] Independent branches can start in parallel. - [ ] Gaps (missing skills, hires, decisions, external inputs) are surfaced, not hidden.