mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-11 14:10:50 +02:00
DottaandPaperclip
16b7db35ff
## Thinking Path > - Paperclip manages work for AI agents. > - Planning guidance helps agents choose owners and dependencies. > - The runtime skill favors few tasks, but the catalog skill requires a child-task breakdown. > - Both add repeated process instructions that can distract from the requested outcome. > - This change keeps the ownership and dependency rules and removes the required matrix and repeated checklist. > - A bounded Product E2E comparison measures saved outcomes and task handoffs before qualification. ## Linked Issues or Issue Description Refs #11057. Related measurement work: #15218. **What existing behavior does this improve?** Planning and delegation through the runtime plan-to-tasks and bundled task-planning skills. **Current behavior** The two skills contain about 1,900 words and conflicting guidance on whether plans require child tasks. **Proposed behavior** Keep cohesive work with one owner. Split only for a real owner, parallel output, dependency, independent review, or follow-up lifecycle. Preserve existing authorization and planning mechanics. ## What Changed - Shorten both skills to about 400 words combined. Preserve their keys and installed-version behavior. - Remove the duplicate operational-skill pointer and regenerate affected source metadata. - Add twelve explicit Product E2E cells: four scenarios with current, short and disabled planning skills. - Use the current task composer and actual create-response ID; calibrate public skill APIs and browser creation without providers. - Eliminate an observed collision in chat-test company prefixes with a per-suite sequence. - Grade saved documents, exact author/run attribution, child count, prerequisite execution order, review boundaries and completion handoffs. - Retain current skill bytes and report source, selections, run accounting and failures. ## Verification - `pnpm test:e2e:runner:typecheck`: pass. - `pnpm test:e2e:runner:unit`: 1,287 Vitest tests and 128 Node checks pass. - `pnpm test:e2e:runner -- --list --suite plan-task-guidance`: twelve local Codex cells. - Archived current skills match master `72ff3a9f27e581a27acb49771e8658bbb0bbaa47` exactly. - Corrected fixture: three real public-API/database calibrations pass with zero provider runs; all 35 evaluator checks and Product E2E typecheck pass. - Setup campaign [37399550253](https://github.com/paperclipai/paperclip/actions/runs/37399550253) was canceled after source review found unsupported bundled edits and automatic core reinstallation. Its paid-cell step was skipped: zero provider runs, no behavioral grade. - The next setup [37401094799](https://github.com/paperclipai/paperclip/actions/runs/37401094799) failed before task creation on the old title-field selector: zero actual runs, original FAIL retained, cleanup passed. A real browser/API calibration of the new helper passes with paused non-provider agents and zero runs. - Full local typecheck/build pass. Full local tests retain one unchanged five-minute Git streaming timeout (also fails isolated), 9,591 passes and 5,796 skips. CI's chat failure was a proven random fixture-prefix collision; five affected cases pass after the test-only repair. - Paid behavior comparison and new-head CI/review remain pending. This PR remains a draft. ## Risks - The shorter text may change delegation decisions. Live outcomes are not yet qualified. - The initial comparison uses one profile and one attempt per cell. It cannot establish cross-model reliability or cost trends. - Disabled means unassigned company-owned copies; the company library remains discoverable. This does not qualify global removal, automatic accepted-plan wiring changes, or installed-copy migration. - Skill availability does not prove a model read or cognitively used it. - No provider/tool protocol, permission, timeout or runtime lifecycle behavior changes in production. ## Model Used OpenAI Codex (GPT-6), with repository inspection, code editing and tool use. The exact backend model ID and context-window size are not exposed in this session. The declared eval model is native Codex `gpt-5.6-sol`. ## 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 - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [ ] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] 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>
85 lines
4.8 KiB
Markdown
85 lines
4.8 KiB
Markdown
---
|
||
name: task-planning
|
||
description: Turn a Paperclip issue or request into a structured implementation plan with child task graph, blockers, owners, and acceptance criteria, then save it as the issue `plan` document.
|
||
key: paperclipai/bundled/paperclip-operations/task-planning
|
||
recommendedForRoles:
|
||
- manager
|
||
- engineer
|
||
- product
|
||
tags:
|
||
- paperclip
|
||
- planning
|
||
- issues
|
||
- delegation
|
||
---
|
||
|
||
# Task Planning
|
||
|
||
Produce implementation plans that the Paperclip executor can actually run: explicit child issues, real blockers, named owners, and a defined acceptance bar. Avoid plans that read well but cannot be split into work.
|
||
|
||
## When to use
|
||
|
||
- An issue asks you to "plan", "scope", "break down", "design the rollout", "propose the work", or similar.
|
||
- A user wants a written plan before approving implementation.
|
||
- A manager needs to delegate non-trivial work and the shape of the work is not obvious yet.
|
||
- You inherited an issue too large to deliver in one heartbeat and need to split it.
|
||
|
||
## When not to use
|
||
|
||
- The issue is a single small change you can ship in the same heartbeat. Just ship it.
|
||
- The issue is forensic ("why did this break"). Use a diagnosis skill first; plan only after the root cause is named.
|
||
- A current `plan` document already exists and the change is minor. Update that document; do not start fresh.
|
||
|
||
## Outputs
|
||
|
||
1. An updated issue document with key `plan` (markdown).
|
||
2. A short comment on the issue that links to the plan document and names the next action.
|
||
3. Where the plan requires approval, an issue-thread interaction of kind `request_confirmation` bound to the latest plan revision.
|
||
|
||
Do not create implementation subtasks until the plan is accepted.
|
||
|
||
## Plan structure
|
||
|
||
Required sections, in order:
|
||
|
||
1. **Goal** — one paragraph. What changes for the user, the operator, or the system once this work lands.
|
||
2. **Context reviewed** — bullet list of documents, files, and prior issues you read. Lets reviewers spot missing inputs.
|
||
3. **Constraints and non-goals** — what must hold (compatibility, security, performance) and what this plan deliberately will not do.
|
||
4. **Approach** — the chosen path, with a short rationale. If you considered alternatives, name them and why you rejected them.
|
||
5. **Work breakdown** — ordered list of child issues. Each child has:
|
||
- Title in imperative form.
|
||
- Owner specialty (Engineer, QA, Designer, Security, DevRel, Manager, etc.).
|
||
- Scope and deliverables.
|
||
- Acceptance criteria.
|
||
- Blocks/blocked-by relationships expressed by phase letter or child title.
|
||
6. **Acceptance** — the bar for the parent issue. How the user knows the whole thing is done.
|
||
7. **Risks and mitigations** — short list. Skip if there are none.
|
||
8. **Deferrals** — what is intentionally pushed to follow-up issues, with why.
|
||
|
||
## Rules of thumb for splitting
|
||
|
||
- One child issue, one specialty. If two specialties have to coordinate inside the same issue, split it.
|
||
- One child issue, one acceptance verdict. If a reviewer would say "this is half done", split it.
|
||
- A child must be checkout-able by the owner from its title and description alone. Reviewers should not have to re-read the parent plan to understand a child.
|
||
- Order children by real blocker chains, not by author preference. Parallel children should explicitly say `blockers: none`.
|
||
- Avoid `polish` or `cleanup` child issues without acceptance criteria — they never close.
|
||
|
||
## Filing the plan
|
||
|
||
Use the Paperclip API to write the plan document, then comment:
|
||
|
||
- `PUT /api/issues/{issueId}/documents/plan` with the markdown body. If `plan` already exists, include the latest `baseRevisionId`.
|
||
- `POST /api/issues/{issueId}/comments` with a short summary that links the plan: `/<prefix>/issues/<issue-id>#document-plan`.
|
||
- 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. 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
|
||
|
||
- Plan disguised as a description edit. Use the `plan` document.
|
||
- "Phases A–Z" with no work breakdown inside the phases.
|
||
- Children with descriptions that say "see parent" — they fail at delegation time.
|
||
- Acceptance written as "code review approval". Reviewers need a behavior bar, not a process bar.
|
||
- Plans that bury blocker chains in prose. Use explicit blocked-by lines.
|