docs-to-types

Docs to Types

Upfront architecture skill for converting clarified prose into typed architecture. If the team knows a durable domain or architecture fact, the type system and module graph should know it too.

Not for general grilling, refactoring review, or the first TDD slice. CONTEXT.md, ADRs, and grill notes are source material, not the final harness.

Prime directive

Do not implement business behavior. Compress approved context into the whole intended typed architecture:

• canonical domain types, schemas, brands, and invariants
• discriminated unions/state models that rule out invalid states
• smart constructors/parsers for values entering from system edges
• service/interface seams using project conventions
• typed result/error families and error translation boundaries
• production/test adapter slots
• composition/layer/module topology using project conventions
• production and test call stacks
• dependency-direction checks where practical

Do not create business workflows, real persistence/network logic, product behavior, after-the-fact refactors, generic mutation/outcome frameworks, or fake production logic pretending to be complete.

Read first

1. AGENTS.md and project coding rules
2. CONTEXT-MAP.md, if present
3. relevant CONTEXT.md files
4. relevant docs/adr/*
5. approved grill-with-docs notes/specs
6. existing source near the target area

If there are no context docs/ADRs and no approved grill-with-docs output, stop and recommend grill-with-docs.

Workflow

1. Extract architecture facts

Before editing, produce a fact table:

| Fact                                        | Source     | Code artifact         | Confidence |
| ------------------------------------------- | ---------- | --------------------- | ---------- |
| Link Catalog is the application-facing seam | CONTEXT.md | `LinkCatalog` service | high       |

Include domain names, ownership boundaries, dependency direction, call stacks, adapter choices, runtime constraints, typed errors, and infrastructure that must stay behind adapters.

2. Ambiguity gate

If docs, code, or user plan conflict, ask one concrete question and wait.

If a prose fact cannot be represented cleanly as a type, seam, adapter, state, error, or dependency rule, treat the domain language as still ambiguous.

Example: CONTEXT.md says “Operator,” but code says “User” and “Actor.” Which is canonical?

3. Propose the typed structure

Before editing, unless the user requested direct implementation, list:

• files to create/update
• domain types/schemas/brands/invariants/smart constructors
• state models/discriminated unions
• service/interface seams
• typed result/error families
• production and test call stacks
• adapter slots/stubs
• architecture checks
• business logic intentionally excluded

Ask for approval.

4. Codify only the typed structure

When approved, write compiling architecture code for the full intended typed structure.

Rules:

• Use project domain names exactly.
• Prefer deep modules: small interfaces, complexity behind the seam.
• Follow project conventions for services, interfaces, DI, composition, layers, factories, providers, or registries.
• Model absence, validation, variants, states, and expected failures with project-native typed patterns.
• Keep HTTP/UI/CLI transport details at their boundaries.
• Keep storage, SQL, queues, RPC clients, SDKs, and third-party APIs behind adapters.
• Add architecture tests/lint/import rules when dependency direction can be checked mechanically.

See REFERENCE.md for allowed code depth and examples.

5. Validate and report

Run narrow checks: typecheck, lint/static checks, and architecture tests if added. Final response: facts codified, files changed, production/test call stacks, adapter slots, checks run, and business logic left unimplemented.