agentleFS
simscalsimscal/sapiens-dtj/.claude/skills/technical-design/SKILL.md

technical-design

Skill0 starsChanged 4 months agoMITView on GitHub

Use when writing, revising, or reviewing a Technical Design Document (TDD) for a feature, epic, or set of user stories. Owns the technical design across backend/frontend/infrastructure and the decomposition of foundational work into `[Tech]` stories — grounded in existing codebase patterns and, when infra is in scope, live infrastructure state. Typically run after stories exist.

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 6 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read CLAUDE.md (+ any role-scoped equivalent) before probing.

    line 40
  2. Very specific:

    One node per component: Never gather multiple components in one box.

    line 103
  3. Very specific:

    Interactions = labeled edges: Every component interaction is a flowchart edge labeled with the call/dispatch/render/consume it represents …

    line 106
  4. Distinctive:

    Bullets/numbered over paragraphs: Never a multi-sentence paragraph where a list works.

    line 114
  5. Very specific:

    Empty section = bare None: No changes / inapplicable / out-of-scope → write exactly None.

    line 121
  6. Distinctive:

    Follow Canonical Sections order — never reorder.

    line 195
  7. Distinctive:

    Follow Writing Style throughout the body — terse, arrows, bullets, deltas only, category-grouped notes.

    line 198
  8. Distinctive:

    Never invent scope — run Discovery.

    line 201
  9. Distinctive:

    Never decide product scope — surface as a blocker if missing.

    line 202
  10. Very specific:

    Never add user-observable behaviour to [Tech] story ACs.

    line 203

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Technical Design Expertise

Workflow

Resolve in-scope roles → probe each role's codebase → fold in design context if supplied (Design context) → run Discovery (answer from probe findings; unresolvable items become blockers) → surface blockers in one message before drafting → draft the canonical sections in order → decompose foundational work into [Tech] stories → validate against Constraints. For revisions, also classify scope impact (Scope Classification + Technical Stories Delta).

Inputs

ParameterRequiredNotes
sprint_goalyesFrom the requirement issue.
storiesyes[{id, title, user_story, acceptance_criteria, notes}] — in-scope user stories. Revisions add per-story implementation status.
requirement_bodyyesFull requirement issue body.
available_codebasesyes[{name, role ∈ {backend, frontend, infrastructure}, path}].
design_contextnoStorybook surface stories — grounds frontend components + scope. placeholder blocks = out of scope (see Design context).
feedbacknoAdjust-loop notes — create iterations only.
existing_tdd_bodynoPrior TDD body. Present ⇒ revision mode → run Classification.
change_intentnoFeature-level scope delta (added/modified/removed). Revisions only; selects what to rewrite.

existing_tdd_body + change_intent present ⇒ revision; else fresh authoring.

In-scope Resolution

RoleIn scope when stories or context imply…
backendpersisted data, new API contract, new event, background job, auth/authz rule, server-side computation
frontenduser-facing surface, page, component, interaction, client-side state/persistence
infrastructurenew cloud resource, queue, cache, third-party integration, IaC module change, environment config

A role not in scope → mark its sections None, do not omit.

Per-role Probe Briefs

Read CLAUDE.md (+ any role-scoped equivalent) before probing. The agent forms its own hypotheses and picks what to read — the table below is orientation, not a checklist. Probe until you can answer the Discovery categories for in-scope roles:

  • Located closest existing analogue for each new component.
  • Identified convention to follow or diverge from.
  • Named where each new piece lives.

Unresolved item -> Discovery blocker. Don't probe indefinitely. Verify, don't assume: confirm each analogue/convention by reading the real file, never from memory of naming. Infrastructure in scope → per resource, call the cloud/platform API for actual current state (running/stopped, attached/detached, exists/missing, rule present/absent) — don't infer it from IaC source. Can't confirm via tooling → Discovery blocker.

RoleStarting points
backendExisting entities, models, DB tables; command/query handlers, services, repositories; API controllers/routes; auth/authz patterns. Record file paths, names, conventions, gaps.
frontendExisting pages, routes, feature folders; components; API client calls/hooks; state slices/query keys. Shared primitives/components/tokens — exist or closest analogue. Record file paths, names, conventions, gaps.
infrastructureExisting modules/resources for the implied capability; config to extend. Record resource names, types, conventions, gaps, plus live-state findings (actual deployed state, not IaC-assumed).

Design context

Caller-supplied design context (Storybook surface stories) grounds frontend component + scope decisions.

placeholder blocks within stories = existing areas the sprint doesn't change (artifacts from ui-design agent, not new scope). Ignore them -> derive no components, data models, API surface, or [Tech] stories from placeholder regions. Design only the changed/new areas.

Discovery Categories

Answer from codebase context first; only unresolvable items become blockers. When surfacing a blocker, state what you inferred -> targeted answer.

CategoryDecisions
Data ownershipNew table vs extend? Which service/DB owns? Shared?
Auth & authorisationRoles/permissions? Resource or role level?
API surfaceNew endpoints or extend? REST or event-driven? Versioning?
Integration boundariesExternal services? Contract ownership?
NFRsLatency/throughput targets? Data volume? SLA?
Real-time vs asyncLive updates, webhooks, polling, batch?
Migration & compatibilityData to migrate? Destructive schema? Backward compat? Confirm current live schema/state before designing the migration.
Infrastructure constraintsCloud/region/cost limits? Ground against live infra state, not IaC-assumed.
RolloutFeature flag? Gradual? Rollback trigger?
Cross-teamBlocking/blocked? Shared contracts?

Canonical Sections

Cover every area in this order. Write None where inapplicable — nothing else, no reason or explanation. Every diagram = Mermaid in a fenced ```mermaid block — never ASCII art. flowchart for structure/components, sequenceDiagram for flows.

#FieldDefine
1high_level_diagramServices, databases, caches, third-party — label new vs existing. Mermaid flowchart.
2data_modelsEntities, relationships, indexes — ERD or schema
3api_specMethod, route, auth, request/response, status codes
4event_schemasTopic, structure, producer, consumer — or None
5happy_pathMermaid sequenceDiagram. Participants must be high-level system modules only: actors (e.g. Customer, Admin) and major system boundaries (e.g. Web, API, Database, External Service). Omit all implementation details — internal libraries, state managers, hooks, query clients, and sub-components must not appear as participants.
6unhappy_pathKey failure scenario and system response. Mermaid sequenceDiagram.
7components_designBackend + Frontend sub-sections. High-level actors only (e.g. endpoint, validator, handler, specification, repository; page, UI sub-component, API client, model layer), tagged [NEW]/[MODIFIED]/[RENAMED]/existing. Diagram = Mermaid flowchart — see Components Design Diagram Rules below. Design decisions (contracts, ordering guarantees, where a responsibility lives) go as terse notes grouped under labeled sub-headings by category (e.g. **Webhook**, **Reads & projections**) — never one flat bullet list.
8infrastructure_designCloud resources added/modified; IaC changes. None if unchanged — bare, no explanation.
9tech_stackNew languages/frameworks/libraries/infra only
10securityAuth, authz, encryption at rest and in transit
11scalabilityThroughput/latency targets, query design, caching, async
12failure_modesMin 2 rows: Scenario, Impact, Mitigation
13migrationData migration, cutover, rollback. Per migration in apply order: fenced ```sql Up (cutover) + Down (rollback) scripts. Or None
14monitoringKey metrics, alert thresholds
15technical_storiesTable: Title, Scope, Required by, Key ACs

Components Design Diagram Rules

Backend + Frontend each render as a Mermaid flowchart TD. Rules:

  • One node per component. Never gather multiple components in one box. Each endpoint/handler/port/impl/hub, each page/hook/transport-module/leaf-component = its own node.
  • Architecture order via subgraph layers. Group nodes by layer, ordered by the stack's dependency direction — backend Domain → Application → Infrastructure / Api; frontend Shell → Hooks → Transport → Components. One subgraph per layer.
  • Location is the only node metadata. Node label = <b>name</b> + tag ([NEW]/[MODIFIED]/[RENAMED]/[existing]) + loc: file path. No responsibility prose, no method signatures, members, validation rules, query keys, hooks/state wiring inside the node — behaviour lives on the edges + the category notes.
  • Interactions = labeled edges. Every component interaction is a flowchart edge labeled with the call/dispatch/render/consume it represents (e.g. OrderCreatedEvent, NotifyOrderPlacedAsync, renders, subscribes via). Port→impl = dotted edge (-.implemented by.->).
  • Verify loc: against the real file. Path must point at the actual file (existing) or its planned path (new) — never guessed.

Writing Style

Governs the <body> markdown. Terse, direct, scannable.

  • Cut filler + articles. Drop words carrying no info ("the", "a", "simply", "in order to", "is responsible for", "note that"). Fewest words per idea.
  • Bullets/numbered over paragraphs. Never a multi-sentence paragraph where a list works. One fact per bullet.
  • Arrows for transitions. → for state moves, flows, routing, mappings (Pending → Processing, handler → repo → table, write → IOrderRepository). Not prose ("transitions to", "is passed to", "which then calls").
  • Describe deltas only. Explain what's [NEW]/[MODIFIED]. Don't explain or re-justify unchanged behaviour — reference it in one phrase and move on. No "X stays the same because…".
  • No hand-holding. Cut restated context, obvious-step narration, and parentheticals that paraphrase the prior clause.
  • Group notes by category under bold sub-headings, not one flat list (see Components Design).
  • Tables for contracts/schemas/failure modes; Mermaid for diagrams.
  • State once. A locked decision stated up front is referenced later, never re-explained.
  • Empty section = bare None. No changes / inapplicable / out-of-scope → write exactly None. No reason, no "what's reused" bullets, no justification.

Technical Story Decomposition

Emit one [Tech] story per discrete piece of foundational work satisfying all:

  • Enables user stories but not user-observable on its own.
  • Developer-verifiable completion condition (build passes, migration runs, primitive matches contract, endpoint returns documented shape).
  • Can't split further into independently-shippable items.

Qualifies: shared component/design primitive, schema migration, IaC module, auth middleware, new event topic + producer scaffold, shared API client. Doesn't qualify (fold into owning user story): single endpoint for one story, single page's local state, copy changes, one-off validation rules.

[Tech] ACs developer-verifiable only — never user-observable. Link dependent user stories via required_by_titles.

Classification (revisions only)

Revisions emit two tables — one per user story, one per [Tech] story.

Scope Classification (per user story)

Compare the revised TDD against each user story (ignore [Tech] stories).

ClassificationConditionAction
additiveAdds new behaviour; existing implementation remains validFlag for incremental work; no rework
breakingConflicts with existing implementationSurface affected files/endpoints; caller decides regenerate vs migrate
structuralRequires full revisit; treat affected files as blank slateList affected files; recommend story regeneration
unaffectedStory not touchedNote and move on

Technical Stories Delta (per [Tech])

Match each [Tech] by title against the baseline TDD's technical_stories table.

ActionCondition
addedNew [Tech] work the baseline TDD lacked.
modifiedExisting [Tech] story whose scope/ACs changed.
removedBaseline [Tech] story no longer required.
unchangedBaseline [Tech] story still valid as-is.

Technical-story Spec

- title: "[Tech] <work item>"
  scope_summary: "<one sentence>"
  acceptance_criteria:
    - "<developer-verifiable AC>"
  notes:
    edge_cases: ["<text>", ...]
    references: [{label: "<text>", url: "<url>"}, ...]
    depends_on_titles: ["<title>", ...]
  required_by_titles: ["<user-story title>", ...]

Returns

$TDD_RESULT:

<tdd>
  <body><!-- full TDD markdown — canonical sections 1–15 in order, present tense --></body>
  <technical_stories><!-- list of [Tech] specs per Technical-story Spec --></technical_stories>
  <scope_classification><!-- revisions only: Scope Classification table --></scope_classification>
  <technical_stories_delta><!-- revisions only: Technical Stories Delta table --></technical_stories_delta>
</tdd>
  • <body> + <technical_stories> always present.
  • <scope_classification> + <technical_stories_delta> present only when existing_tdd_body supplied; omit on fresh authoring.
  • <body> = clean current-state snapshot, never a diff (see Constraints).

Constraints

  • Follow Canonical Sections order — never reorder.
  • Make risks + trade-offs explicit. Rejected an alternative under the current design -> say why in one line. Never narrate a prior version's approach as a rejected alternative.
  • Revised TDD = clean snapshot of the current target design, never a diff against a prior version. Every section in present tense. No change-narration ("previously/now/changed from", "no longer references", "New in this revision", changelog prose), no superseded/prior-version decisions carried forward. Old-code removal = [Tech] story scope, not a design section. Distinct from the codebase-relative [NEW]/[MODIFIED]/existing actor tags in Components Design — those stay.
  • Follow Writing Style throughout the body — terse, arrows, bullets, deltas only, category-grouped notes.
  • Components Design at actor level only — high-level actors + interconnections via Mermaid flowchart edges (one node per component, loc: file path the only node metadata; see Components Design Diagram Rules). Implementation specifics (signatures, members, query keys, state wiring) never appear anywhere in the TDD.
  • Ground every decision in codebase context — cite file paths, existing components, conventions. Justify any divergence.
  • Never invent scope — run Discovery; do not assume product behaviour the caller hasn't specified.
  • Never decide product scope — surface as a blocker if missing.
  • Never add user-observable behaviour to [Tech] story ACs.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.