development-design

Files (9)

• SKILL.md
• claude.md · intelligence/
• codex.md · intelligence/
• gemini.md · intelligence/
• ollama.md · intelligence/
• launcher.md
• change_design_template.md · references/
• change_design_template.preserving.md · references/
• change_design_template.preserving_docs.md · references/

SKILL.md (first lines)

# Development Design

## Purpose

For ongoing work on an existing project: analyze a change request against the existing architecture, name the part that owns each new piece of logic, determine which modules are affected, decompose the work into isolated sub-jobs when needed, and produce a targeted change blueprint.

**Produces:** `change_design.md` — a delta document describing the change, not the full system.

**Decides one header line, `Publishes text:`.** Does this change put text in front of a person to read? `**Publishes text:** yes — <the places the words live>` when it does, `no` when it does not. The chain reads that line to run or pass the `content` step, where the Content Editor writes the words before the Developer places them (`<CORE>/doctrine/flow/development_flow.md` § The stages). A `Behaviour: preserving` change is always `no`, because it adds no words.

## When to Use

- The project already has `docs/adr/`
- The change is scoped — not a full rewrite or new app
- Examples: add a new status value, add a field to an entity, add a new operation, fix an architectural coupling issue, split an oversized module
- **Architect role only.** If invoked outside an architect session, stop immediately and say: "development-design is architect work. Switch to architect? (Open a new session with the `architect:` prefix.)" Stop — no one is there to confirm a switch, and with no change folder resolved there is nowhere to write a report; the chain halts on the missing `change_design.md`.

**Do not use for:**
- New apps or first-time project setup → the foundation step (`product-fdr`, then `product-architecture`)
- Changes that touch every module or require a full architectural rethink → the foundation step, which supersedes a record rather than editing one

## Enter the worktree

development-specs created an isolated worktree for this change and landed `change_spec.md` on the branch — it is **not** on `main`. Before reading anything, derive the worktree from the **change key** and operate inside it for the whole run.

The **change key** is `<YYYY-MM-DD>_<slug>` — the Tobiishi folder (`journey/tobiishi/<key>/`) / branch name. You know it from the invocation (the change you were asked to design). If multiple worktrees exist under `<repo>/.worktrees/` and the intended change is ambiguous, stop, naming the candidates in your closing message — there is no one to ask and no change folder to write into; the chain halts on the missing `change_design.md`.

```bash
REPO_ROOT=$(git rev-parse --show-toplevel)
WORKTREE="$REPO_ROOT/.worktrees/<key>"
test -d "$WORKTREE" || echo "No worktree for <key> — development-specs must run first."
```

If `$WORKTREE` does not exist, **STOP**: the spec stage has not run for this change (development-specs creates the worktree and the spec together). Do not create it here and do not fall back to `main`. With no worktree there is no change folder to write a report into: stop, and the chain halts on the missing `change_design.md`.

**From here on, the worktree is the working root:** read every input from `$WORKTREE/` (`change_spec.md` and the decision files), write `change_design.md` under `$WORKTREE/`, and commit with `git -C "$WORKTREE"`. The change arc stays on the branch, never `main`. The path is derived from the key alone — identical convention to development-specs Step 4 and `ad-hoc-plan`; nothing is handed between sessions.

**Locate the project.** The orchestrator passes the **project name** `<project>` alongside the change key; the change-work folder is `$WORKTREE/system/projects/<project>/journey/tobiishi/<key>/`. The project's decision files are **not** assumed to be at the worktree root — a repo may hold more than one project, each owning its own `docs/`.

**Resolve `PROJECT_DOCS`.** The step resolves the path itself, from the path tool's contract — never from any header in the change_spec (the `Project:` header is retired), and never by composing a product path by hand:

```bash
python3 "<CORE>/tools/development_path.py" resolve --format json \
  --worktree "$WORKTREE" --project <project> --key <key>
```

A non-zero exit is a STOP, with the tool's `message`. From the contract's `product_path`, `product_repo` and `product_worktree`: `<sub>` is `product_path` when it is relative, else `product_path` relative to `product_repo` (`.` when the same), and `PROJECT_DOCS = <product_worktree>/<sub>/docs`. For an in-repo product `product_worktree` is `$WORKTREE`. For an external one it is the product worktree opened for this change — by `create_change_worktree.py`, on the chain path and under `ad-hoc-plan` alike — `<product_worktree>/docs` when `Product path:` *is* the repo root — and **never** the product's primary checkout.

**Every `docs/<file>` reference in the steps below resolves to `$PROJECT_DOCS/<file>`** (`adr/`, `fdr.md`, `nfdr.md`, `SDD.md`) — never the worktree-root `docs/` unless `Product path:` points there.

**Locate the product code — anchor, do not scan.** Blast-radius analysis reads the product's *source* (its `__init__.py` export surface, the affected modules). The source tree is **not** found by searching `$WORKTREE` for "a product folder" — derive it from `$PROJECT_DOCS`:

```bash
PROJECT_ROOT="$(dirname "$PROJECT_DOCS")"   # $WORKTREE/products/<product> (in-repo) or /abs/external-product (external)
```

`$PROJECT_ROOT` is the directory holding the product's `pyproject.toml` / package / tests. **Read all product code strictly under `$PROJECT_ROOT`.** A multi-project instance commits other projects' in-repo products as siblings inside the worktree; for an **external** product `$PROJECT_ROOT` lies *outside* the worktree, so any sibling found by scanning is the **wrong** product — the external-product split-brain. Anchor on `$PROJECT_ROOT`; never scan.

## Pre-flight

Read `$PROJECT_DOCS/adr/` (the decision log and its index), `$PROJECT_DOCS/nfdr.md`, and `$PROJECT_DOCS/fdr.md` if they exist — absence is not an error. These decision files are **optional context**: when present they are first-class inputs — honour the module set and forbidden imports of `nfdr.md § 1.2`, and lean on a record in `adr/` for the *why* behind them once its Status reads **Accepted** (a record still **Proposed** is context, not a binding decision). When `adr/` / `nfdr.md` are absent — a dogfood / FDR-less project with no `docs/` — do **not** halt: fall back to `change_spec.md`'s own module boundaries and the change request for blast-radius scoping. The records sharpen the design when they exist; their absence is never an error.

**Read the parts table, `$PROJECT_DOCS/SDD.md` § 3.** Its `Owns` and `Must not own` columns say which part owns a piece of logic, and `Lives in` says where that part's code is. `nfdr.md § 1.2` cannot answer this, because it is the import graph. Step 2 places every new piece of logic by this table (`<CORE>/doctrine/flow/development_flow.md` § *Code goes where the parts table puts it*, which defines *owning part* and *misplacement*). When the product has no § 3 parts table, the §2 Blast Radius says so, and Step 2 has no placement to make.

**Sweep the records for a gate they delegate to this stage.** An NFDR or ADR entry's `verified by:` tail may name a **review at `development-design`** rather than a check — a clause a command cannot decide, handed to this stage by name. Grep `$PROJECT_DOCS/nfdr.md` and `$PROJECT_DOCS/adr/` for entries naming this stage, and for each one the change touches: perform the review, and record it in `## Architect Review Notes` with its verdict. No later stage inherits it — a downgraded obligation delegated to a pipeline step is invisible to the step it was delegated to, so an unrecorded one is simply never done. The sweep is cheap and the absence is not: reading `nfdr.md § 1.2` alone finds the module set and misses every clause that named this seat.

## Workflow

### Step 1 — Read and understand

Read `change_spec.md` from the product owner's handoff (at `$WORKTREE/system/projects/<project>/journey/tobiishi/<YYYY-MM-DD>_<slug>/change_spec.md`). Derive what the change requires from the existing architecture (module design, schema, operations, dependency graph) and the spec.

**Copy the classification — do not re-derive.** Copy `Category` and `Behaviour` from the `change_spec.md` header **verbatim**; development-design is a *propagator*, never a classifier (`change_classification.md` § *Constraints* — "every downstream artifact propagates them header-to-header"). `Behaviour` selects the drafting mode in Steps 2–7. If the header is missing or out-of-vocabulary (`Behaviour` outside `{preserving, changing}`), **halt** (§ *How this skill halts*) — do not default, do not re-classify; reclassification happens only via the evidence-driven surface-and-halt escape hatch (`change_classification.md` § *Constraints* — "STOP, surface, and reclassify"). See `<CORE>/doctrine/flow/change_classification.md` (`<CORE>` is resolved at session start by the hook).

**No question is asked** — this step runs in the chain, with no one to answer. Derive what the records and `change_spec.md` settle; where the spec is ambiguous or conflicts with itself or the tree, Step 7's reading rule decides, and halts only when no reading keeps every existing contract and delivers the request.

### Step 2 — Blast-radius analysis

For every module in `docs/nfdr.md § 1.2` (the module set), determine its status:

- **Unchanged** — not affected
- **Modified** — something inside changes; state what specifically (new field, new enum value, new method, modified signature, etc.)
- **New** — a new module must be added (rare in ongoing work)

**Before writing the blast-radius table, place every new piece of logic the change adds** — on a `changing` change; a preserving one adds none. For each piece, name its owning part from `docs/SDD.md` § 3 (`<CORE>/doctrine/flow/development_flow.md` § *Code goes where the parts table puts it* defines the term). The module holding that part's `Lives in` unit goes in the blast-radius table as `Modified`, or `New` where the unit does not exist yet, even when the code that first calls the logic sits elsewhere. Its *What changes* cell names the part and the logic. Two cases depart from this, and each is logged in `## Architect Review Notes` as kind (e), below:

- **No part owns the logic.** The note says where it goes, and why no part's `Owns` covers it.
- **The caller may not import the owning part under `docs/nfdr.md § 1.2`.** The design still places the logic in its owning part, and lists `docs/nfdr.md § 1.2` under `## Records this change makes false`, with the import it must allow.

Also check the forbidden-imports graph (`docs/nfdr.md § 1.2`): if a changed module's public interface changes, any module that imports from it may be transitively affected. Include those in the blast radius.

**`Behaviour: preserving` on a product with no code** (a card reading `Test command: none`): every preserving step below swaps modules, symbols and re-exports for documents, sections and invariants, by `<CORE>/doctrine/flow/change_classification.md` § *A product with no code*. Write it with `references/change_design_template.preserving_docs.md`, which settles the blast radius, the Layout Plan, §4 (`None — no code`) and §5 (`No suite`). In place of the five preserving cold-read checks, ask three. Is every invariant from the spec placed? Is any invariant stated twice? Does the design state anything the documents did not? A pointer that says only where a moved statement now stands is not that. A "yes" to the last is a **STOP** for reclassification, the same as check 4's changed signature; never resolve it by narrowing the words, and no `## Architect Review Notes` entry keeps the label.

**`Behaviour: preserving` (relocation / structural change):** the table still lists every affected module, but mark each `Modified (relocation only)` and put *file-location-only* in the *What changes* column. The forbidden-imports **transitive** check is moot — no public interface changes, so no importing module is affected. State that explicitly in the design: "No transitive blast radius — public surfaces unchanged." (Code only: on a product with no code, a document citing a moved statement's old place is in the blast radius.)

Write the blast-radius table:

```markdown
| Module | Status | What changes |
|---|---|---|
| `pkg/domain/` | Modified | Add `TaskStatus.CANCELLED` enum value |
| `pkg/persistence/` | Modified | Serialize / deserialize new status value |
| `pkg/cli/` | Modified | Accept `'cancel'` in `task update --status` |
| `pkg/application/` | Unchanged | — |
```

### Step 3 — Sub-job decomposition

**`Behaviour: preserving` — produce a Layout Plan, not interface-contract sub-jobs.** A preserving relocation exposes no new contract: each affected module keeps its public surface identical, so sub-jobs are independent and there is no build sequence to derive. Instead, for each affected module decide the layout the spec deferred:

- **Named module(s):** the file(s) the implementation moves into (e.g. `domain/project.py`, `domain/errors.py`).
- **Symbol → module mapping:** which classes / functions / module-level constants land in which named module. Account for *every* implementation symbol currently in the `__init__.py`, including underscore-prefixed helpers and constants.
- **`__init__.py` re-exports:** the exact public surface each `__init__.py` re-exports after the move — identical to today's importable symbols, nothing added or removed.
- **Where, not how.** The mapping states *where each symbol lives* — the table is `Symbol | Kind | Target module`, nothing more. Do **not** add an internal-imports column, stdlib-dependency annotations, or any per-symbol import wiring: imports travel with the moved code and are the developer's to write; emitting them leaks implementation into the structural plan and propagates downstream into the developer instruction. Cross-layer import stability is stated once in prose in §1/§2, never as a per-symbol column. If a split risks a **circular import**, flag it once as the hint on that module's §4 row — never as per-symbol wiring in §3.

This is where layout is decided — the thing development-specs deliberately left open. Read the actual code as **structure** (symbol inventory + current location) to plan the mapping; do not re-derive behaviour or re-open the spec's locked Invariants. Name the layout, **not** the move-task sequence — task ordering and red/green discipline are development-plan's job.

Skip the interface-contract / build-sequence machinery below (it applies only to `changing`); go to Step 4.

From eyalgo/kensaiapp, MIT.

More from eyalgo/kensaiapp