Issues
Create and shape GitHub issues with critique, narrow, widen, refine, document.
What it is
Section titled “What it is”Create and shape GitHub issues with critique, narrow, widen, refine, document. This practice is a skill-mapped TTP: when, why, and which command—not a full copy of the skill. Open the skill to execute.
Why it works
Section titled “Why it works”Clear issues are small batches of intent — and the modern home for bug-council culture: file experience failures for users, developers, agents, and ops alike (Bugs & debt). Attach lightweight BDD completion scenarios (Given/When/Then → evidence map) so done is falsifiable (Quality trace); pull product altitude from DocSlime when present. GitHub Issues track owners and PRs; narrowing scope reduces WIP (DORA small batches). Label debt type so the interest is named.
When to use it
Section titled “When to use it”When the situation matches the one-liner above and Orientation (or your project path) says this is the fire to touch now.
- Invoke the skill; follow its safety rules
- Keep one write owner; collect evidence before claiming done
- With only an issue identifier (± details), execute completion work — don’t menu admin commands
- After explicit admin shaping, offer to execute completion (
recon issue, diagnose/fix,check-readiness,merge-it) - Hand off to the next practice instead of boiling the ocean
- Skip orientation when you’re lost
- Spawn overlapping agents to “go faster”
- Treat the practice as done without evidence
Related concepts
Section titled “Related concepts”06-work-ownership, 08-vision-tied-goals, 12-bugs-and-debt, 13-quality-trace
Further reading
Section titled “Further reading”- Quality trace (handbook)
- Bugs & debt (handbook)
- Everything’s a bug (or an issue)
- Dan North — Introducing BDD
- GitHub Docs — About issues
- DORA — Working in small batches
See also the handbook Sources & grounding bibliography.
Agent skill
Section titled “Agent skill”issues