codingthefuturewithai/teamcraft:capture-technical-design

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
7. Review & certify existing docs in place — architecture/decision docs already exist (often inherited or written outside Teamcraft) and the developer wants them verified and certified as accurate, not rewritten

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. When a decision constrains work beyond its own topic — a convergence, migration, phasing, or cross-app pattern that any related work item must respect — make its INDEX summary say so, not merely describe the decision. A consumer scanning the INDEX decides what to drill into from that one line; if the line only names the topic, a cross-cutting decision reads as irrelevant to any work that isn't explicitly about it, and gets skipped. "Service-extraction sequencing — required reading for any work in a module being extracted" pulls the right reader in; "How we extract modules, in what order" doesn't.

Certify the artifacts. Stamp each one with the Teamcraft provenance block per ../references/doc-provenance.md — the architecture doc, the decisions INDEX, and each per-area decision file (each is consulted independently, so each needs its own stamp). When you authored or rewrote content, stamp kind: created. On the review-&-certify-in-place path — the developer confirmed an existing/inherited doc is accurate and you are not rewriting it — insert or refresh ONLY the stamp block (kind: reviewed) and leave the body untouched. Source date from the system clock and plugin_version from the plugin manifest, as the reference describes.

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.