Breakdown — task / design → GitHub issues

This skill takes one of four inputs — a ClickUp task ID, a design doc path, a decision record path (ADR or decision log), or a free-text description — and produces one or more GitHub issues that follow the BeWith 6-section format with AI-assigned effort / urgency / domain labels.

The output is a proposal the developer controls — never something the skill decides and executes. The skill does not open issues without your approval, and the developer (not the AI) decides how many issues to open — including reducing the proposed set to one, or to none (work the task directly). The skill recommends a count and split; you accept, trim, merge, or reject it. Only the set you confirm is opened, in one batch.

When to invoke

Manual entry points:

• /breakdown CU-86ca02ybf — start from a ClickUp parent task.
• /breakdown docs/designs/<slug>-<clickup-id>.md — start from a design doc.
• /breakdown docs/decisions/<slug>.md (or docs/adrs/adr-NNN-<slug>.md) — start from a decision record's action items. This is the usual hand-off from decision-record.
• /breakdown "rewrite the auth middleware to support refresh tokens" — start from a free-text description (no upstream).

Auto-invoke (after explicit user approval): when the developer says something like "OK, let's break this down into tasks" or "create issues for this" and there's a clear scope reference (task, design doc, or recent conversation). Always confirm before generating — issues consume review attention.

Inputs the skill needs

Input	Source	Required?
Scope	one of: ClickUp ID, design doc path, decision record path, free-text	yes
Target repo	the GitHub repo the issues land in (e.g. bewith-dev/backend-api)	yes — ask if unclear
Parent ClickUp ID for back-link	from the input or asked	optional
Default assignee	@me unless told otherwise	optional

If invoked with an ambiguous arg, ask one question — never assume the repo.

Steps

1. Resolve the scope

ClickUp ID: fetch the task via clickup_get_task (MCP). Capture title, description, status, current assignee. If the task has child tasks or linked tasks, surface them — they may already be issues.

Design doc path: read the file. Confirm it follows docs/methodology/planning-docs.md. Extract the proposed breakdown from the relevant section.

Decision record path: read the file. For a decision log entry (docs/decisions/), the Follow-up actions section is the task source. For an ADR (docs/adrs/), use the explicit action items and the Consequences section. Each action item maps to one issue; do not invent work the record did not name. Back-link each issue to the decision record.

Free-text: the description is the scope. Ask the developer for the target repo and any context the description omits.

If the scope is genuinely too large (over ~5 issues), pause and suggest a design doc first — breakdowns deeper than 5 issues are usually a sign that the design wasn't done.

2. Decide zero- vs. single- vs. multi-issue

First: does this even need a GitHub Issue? A small ClickUp task that is itself one piece of work needs none — work it directly (branch → PR referencing the CU-id). A GitHub Issue is for software decomposition; don't open one just to mirror a ClickUp task 1:1 (that's duplication and board noise — see Product↔R&D handoff — "when NOT to create an Issue"). If the input is a small ClickUp task with no real breakdown, say so and stop rather than manufacturing an Issue.

When an Issue (or several) is warranted, the count is the developer's decision, always — not just when it feels ambiguous to you. Present your recommended count + split as a one-line-per-candidate list and let the developer adjust it before you draft full bodies: open fewer, merge two into one, drop some, reduce to a single issue, or decide none are needed. Use the heuristics below to form the recommendation, never to unilaterally settle the number.

Heuristics (for your recommendation):

• One issue when the change is bounded to a single file, single component, single endpoint, single migration, single concern.
• N issues when the work spans frontend + backend, multiple services, or multiple unrelated concerns. Each issue should be independently mergeable.

Never split a single coherent change into two issues "for tracking." Splits should reflect work boundaries. When in doubt, propose fewer issues and let the developer ask for more — over-splitting creates board noise the developer then has to clean up.

3. Draft each issue body

Use the exact 6-section template below (the gh-issue-format convention):

## Summary
One-line description of the change.

## Goal
The "why" with concrete error/behavior. Code blocks where useful (stack traces, before/after snippets).

## <Implementation section>
File path + step-by-step logic. Name the section after the change — "Hook Logic", "Schema Change", "Endpoint Behavior", etc.

## <Registration / wiring section>
Where the change plugs into existing config (settings.json, module.ts, .env, etc.). Skip if not applicable.

## Acceptance Criteria
Bulleted, testable conditions. Must include observable behavior the developer can verify.

## Limitations
Known gaps, edge cases not covered, trade-offs accepted. Write "None identified at design time" if truly empty — do not skip the section.

## Related
Links to ClickUp parent task, prior incidents, related GitHub issues, related skills/agents.

## Definition of Done
<!-- Ordered steps from docs/methodology/definition-of-done.md, rendered so the
     process is visible IN the task — not buried in a skill. Tailor per task:
     keep the Postman line only for HTTP-endpoint work; drop steps that don't apply. -->
- [ ] `lint` / `typecheck` / `test` / `build` green (`/verify`)
- [ ] New behavior has tests (or a written "no tests because:")
- [ ] **API only:** endpoint saved in the R&D Postman workspace with a sample request + saved response example; collection runner green (`postman-endpoint` skill)
- [ ] Changed FE↔BE / RPC contract updated its consumers
- [ ] No secrets in the diff
- [ ] PR draft by default; `/pr-review` before requesting review; CU-id in title + ClickUp link in body
- [ ] AI Context block flushed to both trackers (`state-sync`)

## AI Context (updated by Claude — do not edit manually)

_Seeded empty here; populated on the first `/continue` / `state-sync` run._

Seed the AI Context section. Every Issue body must end with the ## AI Context (updated by Claude — do not edit manually) heading above, left empty. state-sync step 2 replaces this block on each checkpoint — if /breakdown doesn't seed it, the first state-sync run has nothing to replace. Keep the heading text byte-for-byte identical to what state-sync looks for.

No placeholder values. No CU-pending, TBD, xxx — if a section can't be filled, omit it and flag it as an open question to the developer.

The Definition of Done section is mandatory and task-visible. It is the ordered, abbreviated form of definition-of-done.md (the full list + waiver rules live there; process-guardian enforces it at closure). Rendering it into the Issue is deliberate: the steps a developer must do — especially easy-to-forget end-of-dev ones like the Postman save — belong in the task, in order, not hidden in a skill. Tailor the checkboxes to the task (an API task keeps the Postman line; a docs-only task drops it and the contract line).

4. Assign labels

Pick labels per the gh-issue-format convention (effort/urgency/domain). The AI is responsible for the judgment; surface the reasoning in one line of the issue body when not obvious.

Effort is mandatory — never ship an unsized issue: the effort:* label is what makes /next-task --fits-in and the effort tiebreaker work downstream. (ClickUp tasks created outside this skill have no effort — /next-task step 7 offers to size those on read.)

Effort (mandatory, one):

Label	Range
effort:xs	under 1 hour
effort:s	1–3 hours
effort:m	half-day
effort:l	1–2 days
effort:xl	3+ days (consider re-splitting; XL is a smell)

Urgency (mandatory, one):

Label	When
urgency:low	nice-to-have, no concrete blocker
urgency:medium	scheduled work, not blocking
urgency:high	blocks a current sprint / customer
urgency:critical	production-impacting or security

Domain (one or more, when applicable):

domain:backend, domain:frontend, domain:db, domain:ci, domain:auth, domain:design-system, domain:legacy-php, domain:infra, domain:contracts.

The whole effort/urgency/domain vocabulary must already exist on the target repo — gh issue create (step 6) hard-fails if any --label value is missing, so the issue never opens. Onboarding (claude-init) seeds this set via scripts/sync-issue-labels.sh. If you hit a "label not found" error on a repo that wasn't onboarded, run bash scripts/sync-issue-labels.sh <owner/repo> once (idempotent) and retry — don't create labels ad-hoc inline, and don't drop the label from the command.

5. Show the developer the draft

Present each issue as a compact preview:

[Issue 1/3]
Title:  <title>
Repo:   <owner>/<repo>
Labels: effort:m · urgency:high · domain:backend
Body:   <truncated to ~10 lines, full body available on request>

Then ask — framing the count as the developer's choice, not a yes/no on a fixed set:

"Proposal: N issues [list]. Open all of them, a subset, or reshape? I can merge some, drop some, or collapse to a single issue. Tell me which to open — nothing is opened until you confirm the final set."

Default to opening nothing until the developer names the set. If they want fewer, revise and re-show; never open the full N just because no objection was raised.

6. Open the issues

For each draft, run:

unset GITHUB_TOKEN
gh issue create \
  --repo <owner>/<repo> \
  --title "<title>" \
  --body "$(cat <<'EOF'
<full body>
EOF
)" \
  --label "effort:m,urgency:high,domain:backend" \
  --assignee @me

Capture each returned URL. After all issues open, output one consolidated summary:

Opened 3 issues:
  #142 backend: add refresh-token endpoint (effort:m urgency:high)
  #143 frontend: handle refresh in axios interceptor (effort:s urgency:high)
  #144 db: migration for refresh_tokens table (effort:s urgency:medium)
Parent ClickUp: CU-86ca02ybf

7. Back-link to ClickUp

If the input was a ClickUp task, add a comment on the ClickUp task with the GitHub issue URLs via clickup_create_comment (entity_type: "task", entity_id: <task-id>). Format:

Broken down into GH issues:
- <repo>#142 — backend refresh-token endpoint
- <repo>#143 — frontend interceptor
- <repo>#144 — db migration

If the input was a design doc, update the doc's Related or Implementation section with the issue URLs in a follow-up commit — but only if the developer asks. Don't auto-commit edits to design docs.

8. Update active context (optional)

If .claude/session/active-context.json exists in the cwd repo, append the new issue numbers under a pending_issues field. This signals the /continue command (when wired) where to resume.

This step is skipped silently when there is no active-context file.

What this skill does NOT do

• It does NOT open issues without your approval.
• It does NOT decide the issue count. The developer controls granularity — the skill recommends a split, the developer sets the final number, down to one issue or none.
• It does NOT create new labels on the target repo. If a label doesn't exist, surface it; ship the label PR separately.
• It does NOT auto-assign to anyone but @me unless told.
• It does NOT branch or commit code. Branch creation per issue happens via git checkout -b feature/<slug>_CU-<id> later, by the human or by the autonomous-loop command.
• It does NOT translate Hebrew descriptions in the input — issue bodies must be English per feedback-artifact-language. The skill translates a Hebrew input into English on the way to the issue.

Anti-patterns

• Over-splitting. Two issues for a coherent single change is bookkeeping cost without benefit. If one issue would do, write one.
• Under-splitting. A single effort:xl issue is a smell — almost always re-splittable into two effort:ms. Force the question.
• Skipping the Acceptance Criteria section. "It works" is not testable. Acceptance Criteria must be observable.
• Filling Limitations with "None" when there are real edge cases. If you genuinely identified no limitations, say so — but if you skipped thinking about edge cases, the section is the prompt to do it.
• Opening issues from a Hebrew title. Translate first.
• Forgetting the parent ClickUp back-link. Without it, the parent loses track of where its breakdown went. Always comment on the parent unless the input was free-text.
• Creating labels inline. The breakdown skill consumes existing labels; it doesn't define vocabulary.

Cross-references

• decision-record — upstream skill that produces decision records this skill consumes
• docs/methodology/planning-docs.md — design doc convention this skill consumes
• Memory: project_gh_issue_format — the 6-section template + label vocabulary
• Memory: project_workflow_task_lifecycle — where this skill sits in the end-to-end flow
• propose-team-rule, draft-proposal, new-artifact — sibling skills with similar input/draft/confirm/open shape