planning-and-task-breakdown

Files (1)

• SKILL.md

SKILL.md (first lines)

# Planning and Task Breakdown

## Overview

Decompose work into small, verifiable tasks with explicit acceptance criteria. Good task breakdown is the difference between an agent that completes work reliably and one that produces a tangled mess. Every task should be small enough to implement, test, and verify in a single focused session.

In this repo (Mezon Mentor Bot / "MeKnow"), the plan lives in the OpenSpec change: architectural decisions go in `openspec/changes/cNNNN-<slug>/design.md`, UI/visual design goes in `ui.md` (when the change has a user-facing surface), and the task list goes in `tasks.md`. All are generated by `/opsx:propose` and refined here; `/opsx:ship-plan` groups them into test-first work-units and you tick `tasks.md` off during `/opsx:ship-code`.

This is a **polyglot** repo — Python (`uv` workspace), Go (standalone `go.mod` modules, go 1.24), and TypeScript (`apps/portal`). A unit of work is `py`, `go`, or `ts`; the **gate resolver** (`.claude/workflows/lib/gate-resolver.js`) maps each touched path to its owning package and runs that toolchain's gates. Split tasks along package/capability seams so each unit lands in a single toolchain.

## When to Use

- You have an OpenSpec proposal and need to break it into implementable units
- A task feels too large or vague to start
- Work needs to be parallelized across multiple agents or sessions
- You need to communicate scope to a human
- The implementation order isn't obvious

**When NOT to use:** Single-file changes with obvious scope, or when `/opsx:propose` already produced well-defined tasks.

## The Planning Process

### Step 1: Enter Plan Mode

Before writing any code, operate in read-only mode:

- Read the change's `proposal.md` and the relevant `openspec/specs/<capability>/spec.md` baseline (and the linked `docs/design/NNNN-*.md` rationale)
- Read the relevant packages and identify existing patterns and conventions
- Map dependencies between components
- Note risks and unknowns

**Do NOT write code during planning.** The output is `design.md` + `tasks.md`, not implementation. (`/opsx:explore` is the dedicated think-only mode if you need to investigate first.)

### Step 2: Identify the Dependency Graph

Map what depends on what. A MeKnow change typically flows from the data model and policy outward through the retrieval runtime to the answer surface:

```
data model / migration (packages/rag-core, apps/backend/migrations)
    │
    ├── BotPolicy / stage definition (packages/bot-policy)
    │       │
    │       ├── retrieve_kb tool + ACL (packages/rag-core, kb-mcp)
    │       │       │
    │       │       └── retrieval runtime: synthesize/cite/filter (packages/agent-core)
    │       │               │
    │       │               ├── worker / API surface (apps/backend, apps/worker-*)
    │       │               └── portal types (apps/portal — generated from OpenAPI)
    │       │
    │       └── eval-harness golden-set gates (benchmarks/gates, tests/fixtures)
    │
    └── end-to-end check (benchmark gates + cross-tenant isolation tests)
```

Implementation order follows the dependency graph bottom-up: build foundations first. A unit that touches Go (`packages/mello-sdk`, `apps/worker-mello`) or TS (`apps/portal`) is its own seam.

### Step 3: Slice Vertically

Instead of building all the schema, then all the runtime, then all the API wiring — build one complete path at a time:

**Bad (horizontal slicing):**
```
Task 1: Build entire data model
Task 2: Build all retrieval stages
Task 3: Build all API endpoints
Task 4: Connect everything
```

**Good (vertical slicing):**
```
Task 1: BotPolicy stage definition for the new capability (py: packages/bot-policy)
Task 2: retrieve_kb returns ACL-scoped, tenant-isolated chunks (py: packages/rag-core)
Task 3: synthesize/cite/filter produce a cited answer or refuse on no_citations (py: packages/agent-core)
Task 4: Backend exposes it via OpenAPI; portal consumes the generated types (py + ts)
```

Each vertical slice delivers working, testable functionality and is backed by a benchmark gate where it asserts a guarantee (faithfulness, citation accuracy, tenant isolation).

### Step 4: Write Tasks

Each task in `tasks.md` follows this structure. State the unit's **toolchain** so the gate resolver knows which gates apply:

```markdown
## Task [N]: [Short descriptive title]  (toolchain: py | go | ts)

**Description:** One paragraph explaining what this task accomplishes.

**Acceptance criteria:**
- [ ] [Specific, testable condition]
- [ ] [Specific, testable condition]

**Verification (resolver-selected gates for this unit's toolchain):**
- [ ] Python (member dir D): `uv --directory D run ruff check .` · `ruff format --check .` · `uv --directory D run pyright` · `uv --directory D run python -m pytest -q`
- [ ] Go (module dir M): `go build ./...` · `go vet ./...` · `go test -race ./...`
- [ ] TS (apps/portal): `pnpm typecheck` · `pnpm lint` · `pnpm test`
- [ ] Touched packages build/import: `uv --directory D run python -c 'import <pkg>'` / `go build ./...` / `pnpm build` as applicable
- [ ] Benchmarks (py/bench changes): `bash benchmarks/ci-free-gates.sh`
- [ ] Always: `openspec validate "<change>" --strict`
- [ ] Manual check: [what to verify]

**Dependencies:** [Task numbers this depends on, or "None"]

**Files likely touched:**
- `packages/rag-core/src/.../retrieve.py`
- `packages/rag-core/tests/test_retrieve.py`

**Estimated scope:** [Small: 1-2 files | Medium: 3-5 files | Large: 5+ files]
```

### Step 4b: UI Tasks

When the change has a `ui.md` (i.e., a user-facing surface), each UI task should reference the relevant `ui.md` sections and enumerate all UI states:

```markdown
## Task [N]: SearchResultList component with all states (toolchain: ts)

**Description:** Build the SearchResultList component with loading skeleton,
empty-state message, error state with retry, and populated card list.
Follow ui.md → Component Tree for the hierarchy and ui.md → UI States for

From minhlucvan/emdesign, Apache-2.0.

More from minhlucvan/emdesign