docs: clarify plan task dependency handling (#8485)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Paperclip planning skills turn approved plans into executable issue
graphs for agents
> - The executor starts assigned tasks that have no open blockers
> - Parent/child nesting gives structure, but it does not create
execution dependencies
> - Planning guidance that does not make this distinction can let
dependent tasks run too early
> - This pull request clarifies that hard dependencies must be encoded
as `blockedByIssueIds`
> - The benefit is that agents converting plans into tasks have a
clearer checklist for creating and verifying runnable task graphs

## Linked Issues or Issue Description

No public GitHub issue was found for this documentation update.

Problem:
- The planning guidance could be read as if hierarchy, phase order, or
prose blocker notes were enough to sequence execution.
- In Paperclip, only explicit blockers prevent an otherwise-ready
assigned task from starting.

Expected behavior:
- Skill guidance should tell planners to encode each hard dependency as
`blockedByIssueIds` on the dependent issue.
- It should also tell planners to verify the created issue graph before
closing the source planning issue.

## What Changed

- Clarified that parent/child issue nesting is structural and not an
execution blocker.
- Added guidance to build a compact task matrix with task, owner,
initial status, and blockers when converting accepted plans into tasks.
- Added verification guidance to re-fetch or otherwise inspect created
issues before marking the source planning issue done.
- Updated the bundled task-planning skill handoff text to point at the
same dependency expectations without duplicating the full companion
skill text.

## Verification

- Ran `git diff --check origin/master...HEAD` locally.
- Rebased cleanly onto the latest `master` from `paperclipai/paperclip`
before pushing.
- Greptile completed at 5/5 on the latest head; the previous P2 wording
thread was fixed and resolved.
- GitHub PR checks are green on latest head
`2b07db9aef22ca32c65fa66fcca2db86c5b01220`, including policy,
commitperclip review, typecheck/release registry, general test shards,
build, serialized server suites, e2e, canary dry run, verify, Socket,
security-review, Snyk, and Greptile.
- No additional local unit test command was run because this is a
documentation/skill-text-only change and the remote PR suite covered the
repository gates.

## Risks

Low risk. This changes skill guidance only; it does not alter runtime
behavior, database schema, migrations, workflows, or UI code.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

OpenAI Codex, GPT-5-based coding agent in the Paperclip local adapter
runtime. Exact backend model ID and context window were not exposed by
the runtime. Used shell, git, GitHub CLI, and the GitHub connector for
repository inspection and PR creation.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [ ] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

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
 

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.