teamcraft:capture-technical-design

---
name: teamcraft:capture-technical-design
description: Capture or evolve architecture and technology decisions for this project — system structure, components, boundaries, and discrete technology choices with rationale. Handles first-time capture, adding new decision areas, migrations (e.g., Prisma to Drizzle, REST to GraphQL), revisit-when triggers, targeted updates, and architectural evolution. Writes developer-approved gotcha promotions directly. Use when the user says 'capture our architecture', 'document our tech stack', 'add a decision for our new auth approach', 'we're migrating from X to Y', or 'revisit our testing decision'.
argument-hint: "[specific area to focus on (e.g. 'database', 'architecture'), or empty for comprehensive capture]"
disable-model-invocation: false
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - AskUserQuestion
---

## Goal

Own the full lifecycle of this project's architecture and technology decisions. The authoritative artifacts live in two places by default:

- System architecture — single navigable document (opinionated default `/docs/architecture.md`). Architecture is systemic and reads best as one doc.
- Technology decisions — per-area files with an INDEX for progressive disclosure (opinionated default `/docs/decisions/INDEX.md` plus `/docs/decisions/<area>.md`). Decisions evolve independently per area; per-area files let Claude consult only what's relevant.

Specific items Claude would reliably get wrong without always-loaded guidance get promoted into `CLAUDE.md` or `.claude/rules/` with developer approval.

Read `references/example-technical-design.md` first. It shows the shape of both the architecture doc and a decisions/area file, plus how the gotcha-promotion distinction works.

## The Boundary

This skill captures what the team chose and why — architecture and technology. It does not capture team operating conventions (that's `capture-team-conventions`) or product requirements (that's `capture-requirements`). If the conversation drifts, note it and redirect.

## Detect What Exists

Look for existing architecture and decision artifacts. Present what you find briefly before interviewing: "I see architecture documented at [location] and decisions covering [areas]. What are we doing today?"

If existing structure differs from the opinionated defaults, offer migration. If the developer declines, warn that build-loop consultation works by category — Claude locates the files — but mismatched expectations may degrade reliability. Then proceed with the existing structure.

For brownfield projects, look around the repo: dependency manifests, config files, CI, code structure. Draft what's inferable before interviewing.

## Establish Intent

Ask what kind of capture this is. The flow depends on the answer.

Common scenarios:
1. First-time comprehensive capture — nothing documented yet
2. New decision area — existing decisions are documented; adding coverage for a new area (e.g., caching)
3. Migration — replacing one choice with another (Prisma → Drizzle, REST → GraphQL, monolith → service extraction)
4. Revisit-when triggered — a condition from a prior decision's "revisit when" has been met
5. Targeted update — version bump, new constraint, clarification without changing the core choice
6. Architecture evolution — new components, shifted boundaries, deprecations

Don't run a first-time interview on a targeted update. Match the scope of the scenario.

## Ask About External Sources

Ask whether relevant docs exist outside the repo — past ADRs, RFCs, migration plans, vendor comparison docs, prior-art notes from other projects. Read what the developer points you to. Present findings; let the developer decide what applies. Never auto-apply external content.

## Conduct the Capture

Frame the domain and scenario. Claude knows how to interview about architecture and technology stacks — don't recite mechanical question lists. For each decision being captured or updated, aim for the four-part shape:

- What was decided
- Why (reasoning, alternatives considered, what tipped it)
- Constraints (what this means for future work — the rules that follow)
- Revisit when (conditions that would trigger reconsideration; if truly stable, mark it explicitly)

For system architecture, capture components, boundaries, data flow, integration points, deployment model — what describes how the system IS organized.

For migrations, capture both current state and intended direction. Preserve history in the updated decision file so future Claude sessions understand the trajectory, not just the endpoint.

## Present for Review

For first-time captures or migrations, start with a high-level summary before detailed review. Let the developer course-correct before committing to specifics.

For targeted updates, show the specific diff.

## Write the Artifacts

Write to the opinionated defaults unless an existing location was confirmed:

- Architecture → a single navigable document
- Decisions → an INDEX plus per-area files, with the four-part shape per area

For migrations and updates to existing decision files, preserve historical context as a "History" or "Migration Context" section. An agent planning a new feature needs to know the direction, not just the endpoint.

Update the decisions INDEX whenever decision content changes in a way that affects the summary.

## Architecture: Descriptive AND Prescriptive

Architecture documents capture both what IS and what SHOULD BE:

- Descriptive: "We use PostgreSQL 16 with Prisma ORM for existing models."
- Prescriptive: "New features MUST use Drizzle ORM. Don't extend Prisma schemas — we're migrating off Prisma."

This is especially important during migrations, where current state and target state differ. Future work should follow the direction, not the historical pattern.

## Identify and Promote Gotchas

After capturing or updating, walk the artifacts and identify items Claude would reliably get wrong without always-loaded guidance. The test:

> Could Claude figure this out from the codebase, or from reading the decision document when a build-loop skill directs consultation? If yes, it stays only in the document. If no — Claude would default to something from training data without always-loaded guidance — it's a promotion candidate.

Good candidates: non-obvious invariants ("monetary values stored as integers, never floats"), intentional deviations from standard patterns ("no foreign keys on the events table — locking issue"), prescribed direction during a migration ("new code uses Drizzle, not Prisma").

Weak candidates: the choice itself ("we use PostgreSQL" — discoverable from config), the rationale for a choice ("chosen over MongoDB because ACID compliance") — that's reference material, not something Claude acts on every request.

Propose each promotion candidate individually. Show the promotion text and the target location. Developer approves, rejects, or edits. Write each approved promotion directly.

## Respect Domain Ownership

This skill writes architecture, technology decisions, and their gotcha promotions. Nothing else. If the conversation drifts into conventions or requirements, redirect.

## When You're Done

Confirm what was written and where. Surface any promotions that were applied. Ask the developer directly: "Are you satisfied with what was captured?" Wait for confirmation. This skill doesn't decide the work is done.