design-phase-artifacts

name

design-phase-artifacts

description

Use whenever the user asks to "do the design", "design this feature/change", produce design docs, write up an architecture, or plan a non-trivial change before implementation — this is the DESIGN phase of their AI-native SDLC. Trigger it even when they don't say "artifact" or name the documents. It produces a C4 architecture overview plus FIVE Notion design artifacts (Logical Design, Structural Design, Implementation Plan, Test & Verification Plan, Evaluation Plan), each grounded in the real code, and it encodes the content contract for each document plus the Notion publishing and orchestration gotchas. Prefer this over generic planning skills when the deliverable is a design that will be published to Notion.

Design-Phase Artifacts (AI-native SDLC)

What "design" means here

The user's lifecycle is Define → Design → Implement → Evaluate → Release. When they ask for "design", they expect the DESIGN phase worked in full, not a single document. The deliverable is a C4 architecture overview that serves as the single source of truth, plus FIVE artifacts, each published as its own Notion sub-page under the project's design parent page, and each grounded in the real code. Deliver the set, not one doc.

The throughline behind every correction the user has made: design docs describe intent and verification at altitude, as a coherent narrative, grounded in the real scaffolding — not code, not ceremony, not a flat checklist. Hold that altitude and most of the rules below follow naturally.

Ground first, before writing anything

Read the source of truth and the real code before drafting; never invent file or function names.

• The C4 overview design page is the single source of truth. Read it first.
• The SDLC bar comes from the user's playbook in Notion: "01 — The 5 Phases Pipeline" and "The AI-native SDLC". Read both for the per-phase expectations.
• Read the actual code modules you will cite. If a doc claims a function or file, it must exist.

The five artifacts and their content contract

Each artifact opens with a one-line link back to the C4 overview and cross-references the other four by title. Each section opens with short prose, then the diagram or table.

1. Logical Design — what the system does

Behaviour, independent of code shape. Include: testable behavioral requirements derived from the C4 acceptance criteria; the inputs and outputs of each flow; a lifecycle state diagram; the invariants that must always hold; and an "AI Context" section recording the durable WHY (the model has no cross-session memory, so the reason the change exists is written down here).

Fold every decision into ONE cohesive "Design decisions" section, written as flowing prose so the design reads as a whole. Do NOT use ADRs here — no per-entry Status / Date / Context / Decision / Consequences blocks. This is a design, not a decision log. No code.

2. Structural Design — what the code looks like

Where new modules sit (honouring the existing split), what existing modules are reused, the calibration constants named, and a component diagram. Two things the user specifically expects:

• A project file-layout tree, grounded in the project's scaffolding convention. For this user that convention is the polyglot-monorepo-cookiecutter at ~/Projects/workspace/polyglot-monorepo-cookiecutter (src-layout package, flat tests/, ruff + mypy + vulture). Mark new and edited files in the tree, add a placement table (new file → cookiecutter convention → actual repo path → reason), and call out where the repo diverges from the template.
• Interfaces described as high-level OPERATIONS in a table (operation → home module → inputs → output → nature). Do NOT paste function-signature code blocks. The behavioural contracts live in the Logical Design; here you name the operations and their nature.

3. Implementation Plan — a workflow, not a checklist

This reads as a loop, with milestones in narrative form. The structure the user expects:

• A per-step rule: a step is done only when it has been reviewed, simplified, checked for gaps against the design intent, and verified by running something.
• A fixed closing gate at the end of every milestone — the "downward steps": (1) code review the diff, (2) simplify and remove anything the design did not call for, (3) gap assessment comparing what was built to the C4 and Logical Design intent, (4) verify with the milestone's behavioral check plus the full suite and the lint/type/dead-code gate. A milestone closes only on a pass that finds zero gaps; otherwise the gate spawns tasks for the next iteration and the milestone loops.
• A retrospective at the end of each iteration: what was done, and what would have made it faster. The answer updates this workflow, a lint rule, or a skill — the flywheel.
• An overall workflow Definition of Done across dimensions (behaviour, code quality, operational, governance, learning).
• Flag the steps that always need explicit human sign-off (adding a dependency, any destructive operation), and show milestone dependencies and what can run concurrently.

4. Test & Verification Plan — goals and verification methods

Behavioral (end-to-end) checks first, then per-component checks, each traced back to a Logical Design behaviour. State each check as a GOAL plus a VERIFICATION METHOD in given/when/then prose. Do NOT paste test code or pytest bodies. Name the real harness and fixtures, the coverage target, and the pre-commit gate. Keep a table of existing tests to invert or retire.

5. Evaluation Plan — gap analysis in two readiness dimensions

A traceability matrix mapping each design claim and acceptance criterion to its verification. Track CODE readiness (tests green, ruff/mypy/vulture clean, coverage at or above target) SEPARATELY from OPERATIONAL readiness (runs on real data, the model loads, any tunable knob is calibrated, destructive operations verified against a clean git tree, a regression pass). Include a risk register. Calibration of tunable thresholds belongs here, against real data.

Universal rules for every artifact

• High-level descriptions, well-defined goals, and their verification methods. No code in design docs — describe operations in prose and tables. Diagrams as needed (mermaid and file trees are fine; they are not "code").
• Ground every claim in the C4 source and the real code. Never invent names.
• Professional technical writing: concrete, varied sentence openings, minimal dashes, no marketing tone.

Notion mechanics

• Create pages with notion-create-pages: parent is the project's design parent page, properties carry the title, give an emoji icon, and never put the title in the body.
• Edit with notion-update-page: update_content for an anchored search-and-replace (surgical edits, the old_str must match exactly), replace_content for a full rewrite, insert_content to add at the start or end.
• Diagrams: fenced ```mermaid blocks (quote node labels containing parentheses; use
  , not \n). Tables: the XML form, cells hold rich text only.
• C4 colour key: Person #08427B, System #1168BD, Container #438DD5, Component #85BBF0, External #999999, New (added by this design) #FFD43B.
• If unsure about the markdown, read the resource notion://docs/enhanced-markdown-spec with ReadMcpResourceTool (server "plugin_Notion_notion"); do not fetch that URI with notion-fetch.

Orchestration gotchas (this is where time gets lost)

• Subagent Notion MCP access is unreliable. In a five-way fan-out, four agents published and one never connected, despite many retries. Do not assume a subagent can read or write Notion.
• Keep Notion reads and writes in the MAIN session. Subagents do read-only code grounding and DRAFT content; the main session fetches the C4 and playbook and publishes or edits the pages.
• The main thread may be blocked from writing files by an orchestrator hook, while subagents are not. See the cc-hooks-main-vs-subagent and plan-mode-orchestrator-write-deadlock skills. Consequence: even a shared grounding file must be written by a subagent, but the main session can still call Notion MCP tools and Read files.
• Verify published results by fetching the parent page's children, not by trusting agent self-reports — drafting agents often go idle without returning their URLs. See team-mode-orchestration-verification.
• Practical flow: main fetches C4 and playbook → a subagent writes a grounding file distilling them → fan out drafters that read the grounding plus the real code and hand drafts back → main publishes each via notion-create-pages → main verifies via the parent page's child list → main applies edits via notion-update-page.

Worked example — Emergent Tag Taxonomy (karpathy-llm-wiki)

The first full run of this skill. Reuse these page ids to find the playbook and the exemplar artifacts.

• Playbook: "01 — The 5 Phases Pipeline" 38e8e91cd1b98175933ed84e15a536ca; "The AI-native SDLC" 37d8e91cd1b9811b928ac09a556840ea
• Project design parent: "LLM Wiki Taxonomy Extension" 38e8e91cd1b9802eb72ff68ee08b8d09
• C4 source of truth: "Design — Emergent Tag Taxonomy (C4)" 38e8e91cd1b981e1a472c257b7fd6c94
• Logical Design 38e8e91cd1b981d1b474ec6904d7cd55; Structural Design 38e8e91cd1b9815a8601c6e8736cb250; Implementation Plan 38e8e91cd1b9818bb549c228bd3b8248; Test & Verification Plan 38e8e91cd1b98108820be8f566a2f55b; Evaluation Plan 38e8e91cd1b9812480cfd5f77961201d