Init Design

# Skill: init-design

Set up and carry out a new design in `docs/design/designs/<name>/`. Follows the conventions established in `platform-actors` — a brief README index, problem statement, scope, architecture decisions, open questions, and per-concern sub-documents. Ends with scaffolded stubs for each planned document.

---

## Trigger

Invoked when the user asks to start a design for a new feature, module, or cross-cutting concern. Examples:
- "start a design for X"
- "set up the design docs for X"
- "run init-design on X"

---

## Steps

### 1. Clarify scope (ask the user)

Before writing anything, ask two questions in a single message:

> **a. Pull in related context?**
> Should I scan the repo for existing code, specs, or design docs relevant to `<feature>`? (Relevant modules, OpenAPI specs, existing ORM models, etc.) This shapes the problem statement and identifies constraints before you commit to an approach.
>
> **b. Documents to create?**
> Besides README.md, which concern-level docs do you want scaffolded now?
> Suggest a default list based on the feature — the platform-actors design used:
> `actors.md`, `access-scenarios.md`, `endpoints.md`, `openapi-sketch.yaml`, per-actor subdirs (each with `README.md`, `auth.md`, `endpoints.md`), `authorization-server/`.
> Say which you want, or say "suggest" and I'll propose a list with rationale.

Wait for the user's answers before proceeding.

### 2. Pull in related context (if yes)

Search for:
- Existing source modules that the feature touches (grep for the feature noun in `src/`, `openapi/`)
- Existing design docs that mention the feature or its entities
- OpenAPI specs that will need extending
- ORM models and migrations relevant to the new entities
- Existing permission scopes in `admin/core/permissions.py`

Summarise findings in a short bullet list to the user before writing any docs. This becomes the raw material for the "Relationship to existing work" section of the README.

### 3. Write the README

`docs/design/designs/<name>/README.md` — the index and anchor doc for the design. Structure:

```
# <Name> — Design

One-paragraph purpose statement.

## Problem statement
What is broken or missing today? Why does it matter?

## Scope
### In scope
- Bullet list
### Out of scope (deferred)
- Bullet list

## Design documents
Table: | Document | Status | Purpose |
Status values: Draft | TBD | Settled

## Architecture decisions
Key settled decisions with rationale. Use ### subsections per decision.
Name each decision with what was chosen and why, not just what the alternatives were.

## Key questions
Open questions that must be resolved before or during implementation.
Table: | ID | Question | Resolves in |
IDs: OQ-1, OQ-2, … (sequential; carry over if any are already settled)

## Request / interaction flow (optional)
Mermaid sequence or flowchart diagram if there is a clear primary flow.

## Relationship to existing work
Bullet list: what this design extends, replaces, or depends on.
```

### 4. Scaffold sub-documents

Create each planned sub-document as a stub. Each stub contains:
- A `# <Title>` heading
- A one-sentence purpose statement
- `## TBD` section with the key questions or concerns it will address
- A `## Reference` section pointing back to the README and peer docs

Do not write content that is not yet designed. Stubs are intentionally thin — they establish the document's existence and purpose so the README table is not broken, and so each doc can be filled in incrementally.

### 5. Confirm with the user

List the files created (with one-line summaries) and the open questions that need answers before implementation can start. Ask:

> Ready to fill in any of these documents now, or shall we commit the skeleton first?

---

## Conventions (enforced throughout)

These come from feedback on the platform-actors design work:

- **No padding.** Every sentence must earn its place. No meta-commentary ("this section will cover…"), no restatements of what the heading already says.
- **Resolve stale OQ refs.** When an open question is answered, move it out of the open-questions table and into a `### Resolved` subsection below it. Each resolved entry uses the format `#### OQ-N: <full original question text>` followed by a one-paragraph resolution summary and a link to the sub-document where the full detail lives. The full question is the heading — do not shorten it to a topic label. The open table stays clean — only genuinely unresolved questions; resolved ones stay visible with their answers. Add a matching `## OQ-N: <title> — resolved` section in the sub-document itself.
- **Relative paths only.** All cross-document links use relative paths. Verify paths on file creation and on any file rename/move.
- **Mermaid for flows.** Use `sequenceDiagram` for request flows, `flowchart TD` for entity/registration graphs. No ASCII flowcharts.
- **Status column stays current.** The README's document table has a Status column. Update it as documents graduate from TBD → Draft → Settled.
- **Scope = decisions + open questions.** The design is done when every OQ is resolved and every in-scope item has a settled document. Nothing else.

---

## Reference pattern (platform-actors)

The `platform-actors` design is the canonical example of this pattern in this repo:

```
docs/design/designs/platform-actors/
  README.md                         — index, problem, scope, arch decisions, OQs
  access-scenarios.md               — concrete end-to-end access patterns (input to auth design)
  endpoints.md                      — shared OAuth/identity endpoint surface
  openapi-sketch.yaml               — design-time OpenAPI sketch (not production spec)
  actors/
    README.md                       — index for actor-type subdirs
    actors.md                       — entity model: Users, Agents, ServiceAccounts
    agent/
      README.md
      auth.md                       — DCR + JWT Bearer flow; token model; key rotation
      endpoints.md                  — agent-specific HTTP surface
    service-account/
      README.md
      auth.md
      endpoints.md
    users/
      README.md
      auth.md
      endpoints.md
  authorization-server/
    README.md                       — OAuth surface ownership, pluggable IDP scope
    implementation-guide.md         — endpoints, concerns, risks, phased delivery
```

The README is always the entry point. All other documents are reachable from it, and all cross-references use relative paths.