structure

Parse the user's input:

• First argument is the task name (matches the docs directory, e.g., offline-sync)

Phase 1 — Gather existing context

Look for prior work in docs/{task-name}/:

• design.md — design alignment document (from /design) — primary input
• facts.md — codebase implementation facts (from /facts)
• research.md — research findings (from /research)

Read every file that exists.

If design.md does not exist, tell the user: "No design document found at docs/{task-name}/design.md. The structure doc builds on design decisions — run /design {task-name} first, or describe the design intent and I'll work from that."

Also check if docs/{task-name}/structure.md already exists. If it does, this is a resume — read it and skip to Phase 3.

Phase 2 — Create initial structure document

Before writing, explore the codebase to ground every section in reality. Use Glob and Grep to examine:

• Files and modules referenced in design.md and facts.md
• Existing interfaces, data classes, and type signatures in the affected areas
• Current test files and testing patterns near the affected code

Create docs/{task-name}/structure.md with the structure below. Populate every section you can from the gathered context and your codebase exploration. Be concrete — use actual types, file paths, function signatures. No generic placeholders.

# Structure: {Task Name}

## Code Shape

*What the code changes look like. New files, modified files, new types, changed interfaces.*

### New

{Files, modules, classes, or interfaces that don't exist yet and need to be created. For each, describe its responsibility and where it lives in the project structure.}

- `path/to/NewThing.kt` — {responsibility}
  - {key types, classes, or functions it will contain}

### Modified

{Existing files that will change. For each, describe what changes and why.}

- `path/to/Existing.kt` — {what changes}
  - Current: {relevant current signature/shape}
  - After: {what it becomes}

### Removed

{Anything being deleted or deprecated. If nothing, omit this section.}

## Data & Types

*Shape of data flowing through the system. New types, modified types, schemas, contracts.*

{Define the key data structures — dataclasses, TypedDicts, DataFrame schemas, API payloads. Use Python type hints / dataclass-style pseudocode or actual signatures. Show relationships between types.}

```python
# Example — use actual types from the codebase
@dataclass(frozen=True)
class Thing:
    id: ThingId
    field: float

{Call out any data migrations, schema changes, or format conversions required.}

Interfaces & Contracts

Boundaries between components. APIs, repository interfaces, event contracts, module boundaries.

{For each interface boundary that this work touches, show the contract — function signatures, expected inputs/outputs, error cases. Reference existing patterns from facts.md.}

# Example
class ThingRepository(Protocol):
    async def get_by_id(self, id: ThingId) -> Thing | None: ...
    async def save(self, thing: Thing) -> None: ...

Libraries & Dependencies

External libraries, frameworks, or tools involved. New dependencies and how existing ones are used.

{List any new dependencies being added and why. For existing dependencies being used in new ways, note the specific APIs. Include version constraints if relevant.}

Algorithms & Logic

Non-trivial logic, state machines, calculations, or processing pipelines.

{Describe any algorithms, business logic flows, or state transitions that aren't obvious from the interfaces. Use pseudocode, diagrams (in text), or step-by-step descriptions. Skip this section if all logic is straightforward CRUD.}

Change Ordering

What order to make the changes in. Each step should leave the system in a working state.

{Order changes so that each step is independently compilable and (where possible) testable. Group related changes. Call out dependencies between steps.}

1. {Step name} — {what gets created/changed}
   • Files: {list}
   • Depends on: {nothing, or previous step}
   • Verifiable: {yes/no — what you can check after this step}
2. {Step name} — ...

Testing Strategy

How we verify each piece works, and what kinds of tests apply.

{For each step or component, identify what can be tested and how. Be specific about test type, what it covers, and when it can first be run.}

{Call out anything that is hard to test and why. Identify any test infrastructure that needs to be set up.}

Open Questions

Technical unknowns that need resolution before or during implementation.

• {question} — {what it affects in this document}

Technical Decisions

Decisions made during this structure process.

Rules for populating:
- **Code Shape**: Cross-reference `design.md` (end state, approach) with `facts.md` (current state) to derive what's new, modified, and removed. Verify against the actual codebase — don't assume facts.md is current.
- **Data & Types**: Pull from `facts.md` (existing types) and `design.md` (what changes). Show actual Python types where possible, pseudocode for new ones.
- **Interfaces & Contracts**: Pull from `facts.md` (existing interfaces) and `design.md` (approach). Match existing patterns in the codebase.
- **Libraries & Dependencies**: Pull from `research.md` (external findings) and `facts.md` (current deps).
- **Algorithms & Logic**: Pull from `research.md` (external patterns, critical analysis) and `design.md` (approach). Only include non-obvious logic.
- **Change Ordering**: Derive from the dependency graph of the changes. Each step should compile. Prefer vertical slices (one feature end-to-end) over horizontal layers (all models, then all repos, then all UI).
- **Testing Strategy**: Pull from `facts.md` (existing test patterns) and the change ordering. Be specific about what's testable at each stage.
- **Open Questions**: Technical questions only — design-level questions belong in `design.md`. These are things like "does this API support batch writes?" or "can this transform vectorize over the DataFrame, or must it loop row-by-row?"

## Phase 3 — Present and discuss

After creating or reading the structure document, present a summary to the user:

1. **The shape** — overview of what's new, what's modified, what the key types/interfaces look like
2. **The ordering** — proposed sequence and why
3. **Testability** — what we can verify at each stage
4. **What I'm unsure about** — technical open questions, prioritized by what blocks the ordering
5. **What I need from you** — specific technical choices, framed as "A or B" where possible

Then engage in conversation. As the user provides answers, makes decisions, or pushes back:

- **Update the document in-place** using the Edit tool
- **Move answered questions** from Open Questions to Technical Decisions
- **Refine the ordering** as the shape becomes clearer — ordering often changes as types and interfaces solidify

Do not wait for the user to ask you to update the doc. Update it as decisions are made.

## Conversation guidelines

- Be concrete. Show code signatures, not descriptions of code signatures.
- When proposing a type or interface, base it on existing codebase patterns from `facts.md` and your own exploration — don't invent new conventions.
- Frame technical choices with trade-offs: "Option A is simpler but couples X to Y. Option B adds an interface but lets us test X independently."
- If you realize the design doc has a gap that affects structure (e.g., an unresolved design question blocks defining an interface), point it out and suggest updating `design.md`.
- If a question needs codebase exploration, do the exploration right now rather than leaving it as an open question.
- If a question needs external research, suggest `/facts-ext` or `/research` for that specific gap.
- Keep the document as the source of truth. Discussed but not captured doesn't count.
- Sections can be added as needed (e.g., "Migration Steps", "Performance Considerations", "Platform Differences"). The initial structure is a starting point.

## When the user is done

The user may say they're done, or the open questions list may be empty. At that point, **run a
consistency check before the structure is ready for `/better-plan`** (do not skip it):

- **Internal** — does the Change Ordering match the dependency graph of the types and interfaces? Is
  every step independently testable? Is every type/interface that's *referenced* actually *defined*?
  Do the Technical Decisions contradict `design.md`?
- **Against the codebase** — Glob/Grep that every file path, type, and signature cited is real (no
  invented conventions); for greenfield, that it's consistent with the conventions `design.md` sets.
  Fix mismatches.
- Fix what you find; surface anything unresolvable rather than papering over it.

The document at `docs/{task-name}/structure.md` is the deliverable once this check passes.