map-issue-to-tasks

Map Issue → Tasks

Steps 1–3 of the issue lifecycle: analyse an open issue, enrich it against a template, and break it into a dependency-ordered task list. Implementation is a separate skill (fix-mapped-issue).

Plumbing is in issue.sh, next to this file (a sibling of this SKILL.md, wherever your installer placed this skill — e.g. ~/.claude/skills/map-issue-to-tasks/ or ~/.agents/skills/map-issue-to-tasks/). The enrichment template is at templates/issue-enrichment.md, relative to that same directory.

Do this

1. Fetch. issue.sh fetch <n> — read title, body, labels, and existing comments. Note related/duplicate issues. If it's already labeled mapped, say so and confirm before redoing the work.
2. Explore the codebase for the modules/files this touches. Use the project's own affordances (e.g. what-about has a run-what-about skill and a tasks/ convention). Cite concrete file paths.
3. Enrich. Fill the template (copy it, replace the <!-- … --> guidance): Analysis, Context & affected areas, Acceptance criteria, Non-goals, Open questions, Task breakdown. Write it to a scratch file.
4. Derive tasks. Run the spec-driven-development and planning-and-task-breakdown skills to turn the acceptance criteria into small, verifiable, dependency-ordered tasks. Render them in the project's task format — match an existing example if the repo has one (e.g. what-about's tasks/todo.md: **ID — Title** 🔒gate, then Acceptance: / Verify: / Files:, where Verify: always includes the project's quality gate; add dependency/milestone notes à la tasks/plan.md). If the repo has no tasks/ convention, create tasks/issue-<n>-<slug>.md with that shape. Regardless of which format applies, every task heading gets a leading checkbox — - [ ] **ID — Title** 🔒gate — even when matching an existing project convention that doesn't itself use one, so fix-mapped-issue always has something unambiguous to tick after each task merges. If tasks/issue-<n>-<slug>.md already exists for this issue from before this convention (headings with no leading checkbox), retrofit one onto every heading while you're editing the file — - [x] for tasks the file already marks done/merged, - [ ] for the rest — rather than adding new checkbox-only headings alongside old checkbox-less ones.
5. Write outputs (non-destructive):
   • Tasks → tasks/issue-<n>-<slug>.md (issue.sh slug <n> gives the <n>-<slug> stem). Never overwrite an unrelated existing task file.
   • Enrichment → a GitHub issue comment via issue.sh comment <n> <file>. The original issue body is left untouched.
   • Compress the tasks file with caveman-compress. It's read every time an agent picks up this issue, so a leaner file pays off repeatedly. Before invoking it, run the check-caveman-compress.sh next to this file (same directory as this SKILL.md):
     • exit 0 → invoke caveman-compress on tasks/issue-<n>-<slug>.md — trigger it the same way as /caveman-compress <filepath> (see that skill's own SKILL.md for the exact process)
     • exit 1 → not installed anywhere it looked; not a failure — it already printed a warning, skip compression and proceed uncompressed
     • exit 2 → installed but unpatched (its claude --print fallback can leak this host's hooks/MCP context into the file it's compressing — JuliusBrussee/caveman#920, fixed in #921). Stop and surface the script's remediation message to the user — do not run the unpatched compressor and do not silently skip it either, since the whole point is that it's unsafe, not merely absent. This is a temporary guardrail; drop it once the fix has been upstream a while.
6. Label it. issue.sh label <n> — tags the issue mapped (creating the label on first use). This is what lets issue.sh unmapped distinguish issues still needing this treatment from ones already scoped. Do this last, after the enrichment comment has actually posted.