Scope a unit of work into a goals document — defines what and why, not how. Bridge between triage output and dev planning. Produces .work/dev/{identifier}/goals.md for /deep-planning to consume.
Take a unit of work and produce a goals document that anchors why throughout the dev pipeline. Defines what needs to happen, what the user should experience, and what constraints matter — not how to build it.
This is the bridge between triage and dev. Investigation tells you what's broken and where. Goals tell you what the user should experience when it's fixed, what "done" looks like, and what constraints aren't about the code.
/dev-scope <number> # Issue with or without investigation
/dev-scope <number> [number...] # Multiple issues (one goals.md each)
/dev-scope "<description>" # Idea or task with no issue
Detect the gap, recommend the step, don't absorb it. When context is missing (e.g., a bug without an investigation report), tell the user what's missing and recommend the appropriate skill. Do not silently perform another skill's job.
Issue mode (one or more numbers):
gh issue view <number> --repo gitkraken/vscode-gitlens --json number,title,body,comments,labels,state,author,createdAt,updatedAt,milestone,assignees
Determine if the issue is a bug or feature request from its labels, type, and content.
Create the dev folder: .work/dev/<number>/
Description mode (quoted string, no issue number):
Create a descriptive slug from the description (lowercase, hyphens, max 50 chars). Example: "add natural language search" becomes add-natural-language-search.
Create the dev folder: .work/dev/<slug>/
There is no issue to fetch — the description is the entire input. Skip to Stage 2.
For bugs — check for investigation report:
Search for an investigation report that covers this issue:
ls -t .work/triage/reports/*INVESTIGATION-DECISIONS.json 2>/dev/null | head -5
If found, read the JSON and look for an entry where issueNumber matches. If a matching entry exists:
rootCauseSummary, proposedFix, affectedFiles, estimatedEffort, riskLevel, confidence, sourceAttributionIf no investigation report exists for this bug:
Stop and recommend. Present this to the user:
No investigation report found for #NNNN. This is a bug — running
/investigate NNNNfirst will give/dev-scoperoot cause analysis, affected files, and fix direction to build on.Proceed without investigation, or run
/investigatefirst?
Wait for the user's response. If they say proceed, continue with what's available from the issue alone. If they want investigation first, stop and let them run it.
For features and explorations:
No investigation lookup needed. Proceed directly to Stage 2.
Treat every verifiable claim from the issue as a hypothesis. This applies to ALL issue types — bugs and features alike.
What to verify:
package.json or src/config.ts?contributions.json or src/constants.commands.ts?How to verify:
Use Grep and Glob for quick lookups. Read relevant source files when behavior claims need tracing. Do not launch full investigations — this is lightweight verification, not root cause analysis.
Record results in three buckets:
If the issue has no verifiable claims (pure feature request described abstractly), note "No verifiable claims — feature request described in abstract terms" and move on.
This is the layer that investigation reports don't cover and that /deep-planning will lose if nobody writes it down.
For bugs:
For features:
For ideas/explorations:
/deep-planning.Identify the code areas this work will touch. This is not a plan — it's a map so /deep-planning knows where to look.
src/env/node/ vs src/env/browser/), decorator-wrapped methods, high-traffic code pathsFor bugs with investigation reports, the affected files are already known — verify they're still accurate and add any patterns or risk areas the investigation didn't cover.
For features, use Grep and Glob to find analogous features and map the relevant code areas. Reference specific files and functions.
Write specific, testable conditions that define "done." These should cover both technical and UX dimensions.
Good success criteria:
Bad success criteria:
Note things that must not break, performance requirements, environment considerations, and any scope boundaries.
Common constraint categories:
Before writing the goals doc, assess confidence across three dimensions:
This gives /deep-planning actionable signal — "code landscape is Low confidence, verify entry points before committing to an approach."
Write the goals document to .work/dev/{identifier}/goals.md.
# Goals: #{issue} — {title}
(or for ideas without an issue:)
# Goals: {descriptive title}
## Source
- Issue: {GitHub URL or "none"}
- Type: Bug | Feature | Exploration
- Investigation: {path to investigation report entry or "none"}
## Summary
{2-3 sentence distillation of what needs to happen and why. Lead with the user impact, not the technical problem.}
## Verified Claims
{For each verified claim: what was checked and what the code confirmed.
If no verifiable claims: "No verifiable claims — [reason]."}
## Disputed / Unverifiable Claims
{Claims that didn't check out or couldn't be verified. Include what the code actually shows for disputed claims. Critical for /deep-planning — these are landmines.
If none: "All verifiable claims confirmed."}
## Success Criteria
{Specific, testable conditions — both technical and UX.}
## User Experience
- **Trigger**: {what the user does to initiate this}
- **Expected flow**: {step-by-step from the user's perspective}
- **Edge cases**: {what happens when things go wrong, from the user's POV}
- **Workflow context**: {what the user was doing before and what they do after}
(For bugs, also include:)
- **Current experience**: {the broken state}
- **Workarounds**: {if any, and their cost}
## Code Landscape
- **Entry points**: {files and functions}
- **Affected paths**: {code paths that will be modified or impacted}
- **Patterns to follow**: {existing patterns this should align with — reference specific files}
- **Risk areas**: {shared code, cross-environment paths, decorator-wrapped methods}
## Constraints
{Things that must not break, performance requirements, environment considerations, scope boundaries.}
## Investigation Import
(Only present when an investigation report was found. Omit entirely otherwise.)
- **Root cause**: {from investigation}
- **Proposed fix direction**: {from investigation}
- **Affected files**: {from investigation}
- **Effort estimate**: {from investigation}
- **Risk level**: {from investigation}
- **Confidence**: {from investigation}
## Scoping Confidence
- **Claims**: N confirmed, N disputed, N unverifiable
- **Code landscape**: High | Medium | Low — {why, if not High}
- **UX completeness**: Complete | Partial | Minimal — {what's missing}
- **Overall**: High | Medium | Low
When invoked with multiple issue numbers, process each independently. Produce one goals.md per issue in separate dev folders. Present a summary at the end:
Scoped N issues:
- .work/dev/5096/goals.md — #5096: Commit graph branch labels missing
- .work/dev/5084/goals.md — #5084: Blame annotations slow on large files
This skill bridges the triage and dev pipelines:
Triage pipeline Dev pipeline
━━━━━━━━━━━━━━━ ━━━━━━━━━━━━
/triage → /investigate → /prioritize → /dev-scope → /deep-planning → /challenge-plan → [implement]
Upstream: Consumes investigation reports from /investigate (optional, auto-detected).
Downstream: /deep-planning consumes the goals.md produced by this skill.
/dev-scope 5096 # Bug — looks for investigation report
/dev-scope 5096 5084 # Multiple issues — one goals.md each
/dev-scope "natural language search" # Idea — no issue, full extraction
/investigate already ran, import its findings. Don't redo the work./investigate or start planning how. Stay in the what and why.