# Workflow Scoping Process

> Scoping Process

- Skill: `leeovery/workflow-scoping-process` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add leeovery/workflow-scoping-process`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leeovery/workflow-scoping-process/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: leeovery (https://skillmd.com/u/leeovery)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/leeovery/workflow-scoping-process

---


# Scoping Process

Act as **expert technical analyst** performing rapid scoping of a mechanical change. Assess scope, write a lightweight specification, and produce 1-2 task files — all in a single pass.

## Purpose in the Workflow

Scope a mechanical change — gather context, write a specification, and produce a plan with 1-2 task files ready for implementation.

## What This Skill Needs

- **Work unit description** (required) - From the manifest, summarising the mechanical change
- **Topic name** (required) - Same as work_unit for quick-fix
- **Output format preference** (optional) - Will ask if not specified

---

## Instructions

Load **[framework.md](../workflow-shared/references/framework.md)** and follow its instructions as written.

---

## Resuming After Context Refresh

Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol:

1. **Re-read this skill file completely, then re-load [framework.md](../workflow-shared/references/framework.md).** Do not rely on your summary of either, and re-read both even if you believe they are already loaded — that belief is what a summary feels like from the inside. The full process, steps, and rules must be reloaded.
2. **Check what artifacts exist on disk** — spec file, plan file, task files. Their presence reveals which steps completed.
3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits.
4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.

Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.

---

## Hard Rules

1. **Maximum 2 tasks** — if the change needs more, it's not a quick-fix. Promote it.
2. **No acceptance criteria** — mechanical changes are verified by test baselines and completeness checks, not by acceptance criteria.
3. **No agents** — scoping writes specs and tasks directly, without invoking planning agents or review cycles.

---

## Step 0: Resume Detection

Refresh the tmux session label — a no-op unless the user opted in and this session runs inside tmux:

```bash
node .claude/skills/workflow-engine/scripts/engine.cjs session label {work_unit} scoping {topic}
```

Check if a specification already exists:

```bash
ls .workflows/{work_unit}/specification/{topic}/specification.md 2>/dev/null && echo "exists" || echo "none"
```

#### If specification does not exist

→ Proceed to **Step 1**.

#### If specification exists

> *Output the next fenced block as markdown (not a code block):*

```
**`□ Resume Detection`**
```

> *Output the next fenced block as markdown (not a code block):*

```
> An in-progress scoping specification exists — choose whether to pick it up or start fresh.
```

Read the plan and scoping statuses:

```bash
node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.planning.{topic} status
node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.scoping.{topic} status
```

**If plan status is `completed` and scoping status is `in-progress`** (reopened for revisit):

Render the resume menu and emit its section verbatim per its marker:

```bash
node .claude/skills/workflow-engine/scripts/engine.cjs render resume-gate {work_unit}.scoping.{topic} --variant scoping
```

**STOP.** Wait for user response.

**If plan status is `completed` and scoping status is not `in-progress`:**

> *Output the next fenced block as a code block:*

```
Scoping already completed for "{topic:(titlecase)}". Spec and plan are in place.
```

If the scoping status read was empty (item missing), register and complete it:

```bash
node .claude/skills/workflow-engine/scripts/engine.cjs topic start {work_unit} scoping {topic}
node .claude/skills/workflow-engine/scripts/engine.cjs topic complete {work_unit} scoping {topic}
```

→ Proceed to **Step 8**.

**If plan status is not `completed`** (empty or `in-progress`):

The spec exists but the plan is incomplete — an interrupted prior run. Rebuild the context the interrupted run had:

1. Read `.workflows/{work_unit}/specification/{topic}/specification.md` in full — it is the gathered context Step 7 authors tasks from.
2. Read the specification item's status:
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.specification.{topic} status
   ```
   If the output is empty (the run crashed between writing the spec file and registering it), register and index it now:
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs topic start {work_unit} specification {topic}
   node .claude/skills/workflow-engine/scripts/engine.cjs topic complete {work_unit} specification {topic}
   ```
   If the `complete` response carries `warnings`, display them but do not block — the artifact is already saved.
3. Reconcile tasks the interrupted run may already have created in an external backend:
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.planning.{topic} format
   node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.planning.{topic} external_id
   ```
   If both are set, load the format's **[reading.md](../workflow-planning-process/references/output-formats/{format}/reading.md)** and list the tasks already created under `external_id`. Carry that list into Step 7 — existing tasks are adjusted or completed, never re-authored as duplicates. If either read is empty, nothing was authored — resume cleanly.

→ Proceed to **Step 6** (resume from format selection).

#### If `continue`

Load the artifacts as session context: read the spec (`.workflows/{work_unit}/specification/{topic}/specification.md`) and the plan (`.workflows/{work_unit}/planning/{topic}/planning.md`) in full, then read the planning item once — `format`, `external_id`, and `storage_paths` all ride the subtree — and locate and read the task files via the format's **[reading.md](../workflow-planning-process/references/output-formats/{format}/reading.md)**:

```bash
node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.planning.{topic}
```

**If the subtree carries no `storage_paths`** (a plan initialised before the field existed): record it now, before anything commits — read the format's authoring.md → Storage Pathspecs and copy the fenced array:

```bash
node .claude/skills/workflow-engine/scripts/engine.cjs manifest set {work_unit}.planning.{topic} storage_paths '{format storage pathspecs}'
```

> *Output the next fenced block as markdown (not a code block):*

```
Revisiting scoping for "{topic:(titlecase)}".

What should change in the spec or plan?
```

**STOP.** Wait for user response.

Apply the requested edits — the spec and `planning.md` directly, task file content per the format's **[authoring.md](../workflow-planning-process/references/output-formats/{format}/authoring.md)**. Hard rules still hold: maximum 2 tasks, no acceptance criteria. Then:

1. If the spec changed, re-index it (re-completion re-indexes over the same identity):
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs topic complete {work_unit} specification {topic}
   ```
2. Re-complete scoping:
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs topic complete {work_unit} scoping {topic}
   ```
3. Commit each edit under its own scope — the specification with the store its re-completion re-indexed, then the plan with its declared storage:
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs commit {work_unit} -m "spec({work_unit}): adjust quick-fix specification" --topic specification/{topic} --kb --sweep
   node .claude/skills/workflow-engine/scripts/engine.cjs commit {work_unit} -m "scoping({work_unit}): adjust plan" --plan {topic}
   ```

→ Proceed to **Step 8**.

#### If `restart`

Order matters — the plan's cleanup commits while the planning item still exists, so `--plan` resolves the plan's declared storage, and the manifest entries are deleted last.

1. Read the planning item once — `format`, `external_id`, and `storage_paths` all ride the subtree:
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs manifest get {work_unit}.planning.{topic}
   ```
2. **If the subtree carries no `storage_paths`** (a plan initialised before the field existed): record it now, before anything commits — read the format's authoring.md → Storage Pathspecs and copy the fenced array:
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs manifest set {work_unit}.planning.{topic} storage_paths '{format storage pathspecs}'
   ```
3. Load the format's **[authoring.md](../workflow-planning-process/references/output-formats/{format}/authoring.md)**
4. Follow the authoring file's cleanup instructions to remove authored tasks for this topic — the cleanup targets the entity identified by `external_id`
5. Delete the spec and plan files: `rm -rf .workflows/{work_unit}/specification/{topic}/ .workflows/{work_unit}/planning/{topic}/`
6. Remove the spec's knowledge-base entry:
   ```bash
   node .claude/skills/workflow-knowledge/scripts/knowledge.cjs remove --work-unit {work_unit} --phase specification --topic {topic}
   ```
7. Commit the plan's cleanup — `--plan` stages the planning topic, both manifests, and the plan's declared storage, so the deleted plan files and the format's own cleanup land together:
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs commit {work_unit} -m "scoping({work_unit}): restart scoping — clear the authored plan" --plan {topic}
   ```
8. Delete the specification and planning manifest entries — the scoping item stays `in-progress`; the fresh run re-completes it at Write Tasks:
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs manifest delete {work_unit}.specification items.{topic}
   node .claude/skills/workflow-engine/scripts/engine.cjs manifest delete {work_unit}.planning items.{topic}
   ```
9. Commit what remains — the deleted specification, the store the removal emptied, and the two manifest entries. A quick-fix's topic is its work unit, so the work-unit scope is this action's own:
   ```bash
   node .claude/skills/workflow-engine/scripts/engine.cjs commit {work_unit} -m "scoping({work_unit}): restart scoping"
   ```

→ Proceed to **Step 1**.

---

## Step 1: Knowledge Usage

Load **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)** and follow its instructions as written.

→ On return, proceed to **Step 2**.

---

## Step 2: Gather Context

> *Output the next fenced block as markdown (not a code block):*

```
**`□ Gather Context`**
```

> *Output the next fenced block as markdown (not a code block):*

```
> Understanding what needs changing — reading code, asking clarifying questions, and building a picture of the change.
```

Load **[gather-context.md](references/gather-context.md)** and follow its instructions as written.

*Knowledge-base nudge — if the change touches an area with prior discussions, investigations, or specs, query the knowledge base while gathering context. A "mechanical change" often has a history. See **[knowledge-usage.md](../workflow-knowledge/references/knowledge-usage.md)**.*

→ On return, proceed to **Step 3**.

---

## Step 3: Contextual Query

Load **[contextual-query.md](../workflow-knowledge/references/contextual-query.md)** and follow its instructions as written.

→ On return, proceed to **Step 4**.

---

## Step 4: Complexity Check

Load **[complexity-check.md](references/complexity-check.md)** and follow its instructions as written.

→ On return, proceed to **Step 5**.

---

## Step 5: Write Specification

> *Output the next fenced block as markdown (not a code block):*

```
**`□ Write Specification`**
```

> *Output the next fenced block as markdown (not a code block):*

```
> Writing a lightweight specification for the change. This captures what's changing and why.
```

Load **[write-specification.md](references/write-specification.md)** and follow its instructions as written.

→ On return, proceed to **Step 6**.

---

## Step 6: Select Output Format

> *Output the next fenced block as markdown (not a code block):*

```
**`□ Select Output Format`**
```

> *Output the next fenced block as markdown (not a code block):*

```
> Choosing the output format for task files.
```

Load **[select-format.md](references/select-format.md)** and follow its instructions as written.

→ On return, proceed to **Step 7**.

---

## Step 7: Write Tasks

> *Output the next fenced block as markdown (not a code block):*

```
**`□ Write Tasks`**
```

> *Output the next fenced block as markdown (not a code block):*

```
> Writing 1-2 task files for the change. Quick-fixes are limited to two tasks maximum.
```

Load **[write-tasks.md](references/write-tasks.md)** and follow its instructions as written.

→ On return, proceed to **Step 8**.

---

## Step 8: Conclude Scoping

> *Output the next fenced block as markdown (not a code block):*

```
**`□ Conclude Scoping`**
```

> *Output the next fenced block as markdown (not a code block):*

```
> Wrapping up. Spec and plan are ready for implementation.
```

Load **[conclude-scoping.md](references/conclude-scoping.md)** and follow its instructions as written.