scope

Files (1)

• SKILL.md

SKILL.md (first lines)

# Scope

Break down a task into a phased plan before jumping into code. Think first, build second.

## When to use

- Before starting any non-trivial feature or refactor
- When a task touches multiple files, modules, or systems
- When the approach isn't obvious and you want to align before coding
- When the user asks "how would you approach this?" or "what's the plan?"
- Before parallel agent work (each agent needs a clear scope boundary)

## Inputs

Gather enough context to plan, but don't over-research:

1. **Task description**: what needs to happen (from user or issue)
2. **Codebase recon**: read relevant files, understand current structure
3. **Constraints**: deadlines, compatibility requirements, things that must not break
4. **Prior art**: has something similar been done in this repo? Follow the pattern or explicitly decide not to.

## Scoping process

### Step 1: Restate the goal

Write a single sentence describing what "done" looks like. This is your north star.
If you can't write this sentence, the task isn't clear enough — ask.

### Step 2: Identify the change surface

List every file, module, API, database table, or config that will be touched.
For each, note whether it's a create, modify, or delete.

Use `grep`, `glob`, and file reads — don't guess.

### Step 3: Identify risks and unknowns

What could go wrong? What don't you know yet?

Categories:
- **Breaking changes**: callers, consumers, downstream systems
- **Data concerns**: migrations, backfills, backward compatibility
- **Performance**: will this change hot paths? Add load?
- **Security**: new attack surface? Auth changes? Input handling?
- **Dependencies**: new packages, version constraints, license issues
- **Unknowns**: things you need to investigate before committing to an approach

### Step 4: Break into phases

Each phase must be:
- **Independently verifiable** — has a test gate (automated test, manual check, or both)
- **Safely commitable** — the codebase works after each phase, even if the feature is incomplete
- **Small enough to review** — if a phase would produce a 500-line diff, split it

Phase structure:
1. Description: what this phase does
2. Files touched: specific paths
3. Test gate: how to verify this phase is correct
4. Dependencies: which phases must complete first
5. Estimated complexity: trivial / moderate / complex

### Step 5: Define the verification plan

How do you know the whole thing works? Not just "tests pass" — what does the user see?
What would a manual smoke test look like?

## Output format

```markdown
## Scope: <task title>

**Goal:** <one sentence — what "done" looks like>
**Complexity:** trivial | moderate | complex | needs-spike
**Estimated phases:** <N>

### Change surface

| Path | Action | Notes |
|------|--------|-------|
| `src/foo.py` | modify | add new endpoint |
| `tests/test_foo.py` | create | cover new endpoint |
| `db/migrations/003.sql` | create | add column |

### Risks & unknowns

- <risk 1: description + mitigation>
- <risk 2: description + mitigation>
- <unknown 1: what needs investigating + how>

### Rollout & operability

- **Rollout strategy:** big-bang | feature flag | gradual | canary
- **Rollback plan:** <how to revert if things go wrong>
- **Observability:** <logging, metrics, or alerts to add/modify>
- **Backward compatibility:** <API consumers, queued jobs, cached data affected?>

### Phases

#### Phase 1: <title>
- **Do:** <what to implement>
- **Files:** `path/a`, `path/b`
- **Complexity:** trivial | moderate | complex
- **Test gate:** <how to verify>
- **Depends on:** none

#### Phase 2: <title>
- **Do:** <what to implement>
- **Files:** `path/c`, `path/d`
- **Complexity:** trivial | moderate | complex
- **Test gate:** <how to verify>
- **Depends on:** Phase 1

#### Phase 3: <title>
- **Do:** <what to implement>
- **Files:** `path/e`
- **Complexity:** trivial | moderate | complex
- **Test gate:** <how to verify>
- **Depends on:** Phase 1, Phase 2

From clemens33/dotfiles, MIT.

More from clemens33/dotfiles