scope-issue
Skill2 starsChanged 19 days agoMITView on GitHub
Writes issue descriptions: a problem paragraph opening with the defect, a proposal, then a `## Done when` section of observable checks, and opens a docs MR with the record of a hard-to-reverse design choice the proposal cites. Use when writing or editing an issue (`gh issue create`, `gh api …/issues`, `glab issue create`, `-f description=`). Commit messages: use `scope-commit`; MR/PR descriptions: use `scope-mr`.
In this repository16 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ask-teamSkill
- assemble-metaSkill
- brainstormSkill
- build-issueSkill
- cut-milestonesSkill
- frictionSkill
- milestone-closeSkill
- qa-reviewSkill
- review-benchSkill
- scope-commitSkill
- scope-mrSkill
- scope-specSkill
- setup-dream-teamSkill
- ship-itSkill
- triage-issueSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 20
Every issue answers: what do I do next.
- Distinctive: line 21
Every issue answers: how do I know it's done.
- Distinctive: line 36
Never end at the problem.
- Very specific: line 64
Commit the record and the files repo-conventions.md and references/glossary.md add with it, nothing else, on its own branch per …
- Very specific: line 101
Every open blocker of a piece is another child of the same meta issue → file it as a child, with one Blocked by #<n> line per sibling.
- Very specific: line 144
Default: plain - bullets.
- Distinctive: line 162
No inline code for emphasis or ordinary nouns.
- Very specific: line 174
Never on a Research:, Evidence: or Meta: issue.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Issue is actionable items, not prose. Read days or weeks later with zero conversation context.
issue-style
Reader starts the task from the description alone — no chat history. Comments carry the issue's history; a run that resumes the work reads them too.
Goal
- Every issue answers: what do I do next.
- Every issue answers: how do I know it's done.
Shape
- Three parts, in order: problem, proposal,
## Done when. - Problem opens the description unlabeled. No
## Problemheading. - Problem opens with the defect or gap, bolded.
- Background the defect or gap needs follows it.
- Several defects, effects or sites → a
-list after the opening sentence. - Evidence (a table, a fenced block) sits under the claim it backs.
- Origin is one clause ("Found by a docs review").
- Each fact appears once.
- Proposal: the next step, under
## Proposal. Always present, except a meta or bundle issue. - Proposal is concrete: a list of actions, a person to engage, or a research issue's questions.
## Done whenfollows## Proposal: one plain-bullet per observable check. No- [ ]boxes. Not in a meta or bundle issue.- Never end at the problem.
- Meta issue: a paragraph on the work it tracks, then the checklist. No bolded defect, no
## Proposal. - Bundle issue: a paragraph on what its items share, then
## Items. No bolded defect, no## Proposal. - One kind label:
bug,feature,maintenance,performance,researchormeta.
Open questions
- User asked for the issue in chat, no open question or each one settled by reading the code or the reference source → ask nothing.
- User asked for the issue in chat, a choice that would pass the test in
<base directory>/../build-issue/reference/decision-record.mdonce decided, its options not yet known, or a## Done whencheck with no observable form → rundream-team:brainstorm, skipping its path proposal and hand-off, until the choice is decided and each check is observable; the issue is the path (Decisions writes its record). - User asked for the issue in chat, any other open question, milestone included → ask it with AskUserQuestion before writing it; write the answers into the issue.
- Issue found during other work (build-issue, a review, a lab check) → do not prompt; list the
open questions as open items in the proposal, or file a
Research:issue. - Issue found during other work, not a
Research:issue, open items in its proposal → add theworkflow::needs-brainstormlabel.
Decisions
- Proposal carries a decided design choice that passes the test in
<base directory>/../build-issue/reference/decision-record.md→ before filing, write its record at the path, naming and template<base directory>/../../references/repo-conventions.mdresolves. - That reference resolved a non-default convention → put its
Conventions:line in the reply. - Commit the record and the files
repo-conventions.mdandreferences/glossary.mdadd with it, nothing else, on its own branch perscope-commit, push it and open its own docs MR perscope-mr. - Cut that branch in its own worktree from the fetched tip of the remote's default branch, never
from the current checkout:
git worktree add -b decision-<slug> .claude/worktrees/decision-<slug> origin/<default>. - Docs MR open →
git worktree remove .claude/worktrees/decision-<slug>. - The issue cites the record path and the docs MR link at the choice; the body never argues it.
- A choice still undecided after Open questions has no record: it stays an open question.
Research
- Proposal would need a guess or an assumption no Open questions tier settles → research issue, not a guessed proposal.
- Title starts
Research:. - Proposal lists the questions to answer.
- Deliverable: a findings comment on the issue plus follow-up issues for the gaps found (Bundle). No code.
- User asks for a file → a note in the repo's research docs; the comment carries the rest.
- A research issue's
## Done when: every question has an answer or an issue tracking it.
Evidence
- Milestone exit gate is field evidence → one evidence issue in that milestone.
- Title starts
Evidence:. - Proposal lists what to deploy and where, the start date, the measurement, and how to collect it.
- Closes with the milestone.
Meta
- Work spans milestones, waits on features not built yet, or is a milestone's unattended issues (below) → one meta issue tracking it.
- Title starts
Meta:. - The checklist follows the opening paragraph, under no heading; one line per piece of work.
- A line is a child issue link, or plain text naming the feature it waits on, outside the meta issue.
- File a child issue when its work can start; tick its box when it closes.
- Every open blocker of a piece is another child of the same meta issue → file it as a child,
with one
Blocked by #<n>line per sibling. - A meta issue for work spanning milestones has no milestone; each child carries its own.
- Closes when every line is ticked or ruled out.
- User asks to file a milestone's issues under one meta issue → one meta issue set to that milestone, its lines the milestone's issues that can run unattended.
- A run files two or more non-
Research:issues in one milestone that pass step 2 of<base directory>/../build-issue/SKILL.md, carry noworkflow::needs-brainstormorworkflow::blockedlabel and need no lab work → file them under one meta issue set to that milestone, without prompting, whatever their kind label. - A bundle issue (Bundle) counts as one issue toward that count.
- Filing a milestone's meta issue on request → propose the issues that stay off it as human-loop issues (they need a lab run, credentials, or a product or UX call) in the same AskUserQuestion batch, for the user to confirm.
Bundle
- One run files two or more findings, each light tier on its own per step 2a of
<base directory>/../build-issue/SKILL.md→ one bundle issue. - At most ~6 items; the rest start another bundle, or a plain issue when one is left.
- Items may carry different
area::labels. - Title names the group.
## Items: one- [ ]line per item, giving its defect, the exact edit and its done-when.- Labels: the items' majority
area::and majority kind. - A lone light-tier finding → a plain issue.
Blockers
- Work cannot start until another issue closes → a
Blocked by #<n>line, one per blocker. - Blocker lines end the description.
- Filed into a milestone whose description's
Depends on:has an open milestone → theworkflow::futurelabel.
Title
- Under 80 chars.
- Name the thing, not the history.
- ❌ "Refactoring the plugins structure to take into account changes in the Express.js library".
- ✅ "Plugins structure refactoring".
Items
- Multi-part work →
-bullet list. - Each item independently completable and verifiable.
- Default: plain
-bullets. - [ ]boxes only for complex multi-stage work, a meta issue's checklist, or a bundle's items.- A paragraph contains an action → pull the action into an item; the paragraph keeps only the why.
- Terse only after the next action is stated. "Stand up the lab" is a title, not a description.
Skimming
- Problem holds only what's needed to act. The reader already works on the project.
- Cite a brief or doc the target forge's readers can open by URL or path, at the claim it backs; don't repeat it.
- Problem carries the substance. Longest part.
- Proposal and
## Done whenare the outro.
Format
- Bold the claim a skimmer must land on, not a keyword.
- One bolded phrase per paragraph at most.
- Inline code for identifiers only: file, path, command, config key, label, version, symbol.
- No inline code for emphasis or ordinary nouns.
- Two or more commands or snippets → one fenced block, a
#comment per case; never inline code in bullets. - One line per paragraph or list item; never hard-wrap.
Diagram
- Defect or new design is a relationship between 3 or more named modules or paths → one fenced
mermaiddiagram showing it. - The diagram replaces the prose it depicts.
- At most 8 nodes.
- No styling.
- Each node names a real file, symbol or output.
- Never on a
Research:,Evidence:orMeta:issue. - Syntax:
graph TD,id["label"],-->,-.->andsubgraphonly; neverflowchart,%%{or@{. - Node id is a short alphanumeric word, never
end. - Unsure whether to draw, user asked for the issue in chat → ask the user.
Names
- Describe behaviour in plain words; a backticked code name is the exception.
- Terms, in the issue and its decision record: follow
<base directory>/../../references/glossary.md. - User-facing name (flag, config key, metric, exit code, error string) → no limit.
- Code name (function, type, field — own code or library) → at most three backticked occurrences in the whole text.
- Detail that locates a site or names a customer or person outside the project (city, address, coordinates, company, contact) → leave it out unless the work depends on it.
- Issue, MR, repo, link or path the target forge's readers cannot open (chat thread, shared doc, local file, internal host) → describe it in plain words, or drop it.
Updates
- An open issue's comments hold every result a later run needs: findings, decisions, progress.
- Repo docs hold only facts that outlive the issue.
- Small amendment that leaves the work remaining unchanged → a new comment; leave the description as written.
- Finding with no decision on direction yet → a new comment; leave the description as written.
- Direction decided, title and problem paragraph still hold → rewrite the proposal and
its
## Done whensection, then comment why it changed with the replaced proposal quoted. - Direction decided, title or problem paragraph no longer holds → file a new issue that links the
findings comment, then close this one with a
Superseded by #<n>comment. - Description is the current spec. Comments are the log.
Length
- ~250 words the shape. 500 hard cap, except the two cases below.
- Fenced blocks are evidence or a diagram, not prose; they don't count toward the cap.
- Background overgrows first. Cut it first.
- Still over 500 with every fact one the next run needs, user asked for the issue in chat → before filing, give the word count and ask: split into a meta issue with children, or file over the cap.
- Still over 500 with every fact one the next run needs, issue found during other work → file it over the cap; name the issue and its word count in the run's report.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

