Polish Issue Scope (Single Feature)

Goal: turn one issue into a complete, actionable spec for a single feature or fix. Keep it concise, technical, and executable without follow-up questions.

Use When

• Issue is missing scope, acceptance criteria, or validation.

• Issue references a feature/fix but lacks file touchpoints or constraints.

• You need an execution-ready issue for a coding agent.

Do Not Use

• Multi-epic planning or multi-sprint roadmaps.

• Full product/spec interviews (use the interview skill for that).

Workflow

• Fetch the issue

gh issue view <number> --repo <owner/repo> --json title,body,labels,state,comments

• Scan the codebase

• Locate related files or patterns with rg .

• Identify likely files to modify or create.

• Note constraints (existing APIs, data models, UI patterns, tests).

• Resolve blockers

• Ask all blocking questions for the issue.

• If not blocking, confirm assumptions with user before proceeding.

• Draft a concise scope block

• Keep to bullets, no fluff.

• Provide enough context to implement without follow-up.

• Show preview and confirm

• Present exact markdown to append.

• Wait for explicit approval before editing the issue.

• Update the issue

CURRENT_BODY=$(gh issue view <number> --repo <owner/repo> --json body -q .body)

gh issue edit <number> --repo <owner/repo> --body "$CURRENT_BODY

[scope block here]"

Scope Block Template

Scope

Summary

• <1-2 sentence summary of the change>

Assumptions

• <explicit assumptions or defaults made>

Goals

• <what must be true when done>

Non-goals

• <explicitly out of scope>

User impact

• <who is affected and how>

Touchpoints

• Modify: path/to/file.ts - <why>
• Create: path/to/new-file.ts - <why>

API/data changes (if any)

• <schema, endpoints, migrations>

Edge cases

• <list>

Acceptance criteria

• <testable outcome>
• <testable outcome>

Validation

• Tests: <command or file>
• Manual: <steps>

Task breakdown (atomic, commit-ready)

1. <task title>
   • Inputs: <files/data/flags>
   • Outputs: <artifacts/changes>
   • Steps: <1-3 concrete steps>
   • Validation: <test or check>
   • Complexity: <1-10>
2. <task title>
   • Inputs: <files/data/flags>
   • Outputs: <artifacts/changes>
   • Steps: <1-3 concrete steps>
   • Validation: <test or check>
   • Complexity: <1-10>

Dependencies / risks

• <libs, feature flags, env vars, rollout concerns>

Rules

• Prefer explicit file paths and code locations.

• Each task must be small and independently verifiable.

• Each task must include inputs/outputs and 1-3 concrete steps.

• Complexity is a 1-10 estimate; split tasks above 7.

• If there are multiple viable approaches, list them briefly and pick a recommendation unless the choice blocks implementation.

• Avoid long narrative; keep it scannable.