Skip to content

skill · phase: design

Design Phase

Purpose

Produce a technical design that satisfies the requirements. Define architecture, interfaces, data models, and integration points before writing code.

Entry Criteria

{{glossary:instance}}

  • Requirements phase complete
  • The instance is claimed by this session

Entering in a fresh session

Read only:

  • instance.yaml
  • requirements.md — in full; the acceptance criteria are what the design is traced against
  • the always-read guidance layers named in .aidlc/guidance/index.yaml (see The always-read rule in aidlc-overview)
  • .aidlc/context/architecture.md and style-guide.md
  • .aidlc/context/constitution.md, when it exists

The seams the requirements touch are then read from the source, as step 3 of the instructions says — a handful of files, not a survey, and not the previous phase's transcript. See The context rule in aidlc-overview.

Required Artifacts

  • design.md — Architecture overview, component design, interfaces, data flow, and design decisions with rationale

Instructions

{{glossary:gate}}

  1. Review requirements. Read requirements.md (or its summary if one exists). Identify the key technical challenges. When requirements carry AC-n IDs, note in each design section which criteria it addresses — that linkage is what reviewers and the testing phase trace against.
  2. Consult the knowledge graph, then check it against the source. If the project has a knowledge graph (.aidlc/knowledge/ exists), run aidlc knowledge context --scope phase --phase design for existing architecture, decisions, and conventions. The graph is an index into the code, not an authority over it: an entry naming a component, table, column, function, or registry is a pointer to open, and an entry written by an earlier instance may name something a later one renamed or deleted. Confirm a named symbol exists in the source before designing against it — aidlc knowledge verify <id> records that you did, and aidlc knowledge update <id> corrects an entry that no longer matches. A design built on a symbol that is not there produces code against an API nobody has, and nothing downstream catches it until implementation. Also read the always-read guidance layers from .aidlc/guidance/index.yaml — see The always-read rule in aidlc-overview for which layers those are and when to reach for the full lessons.md. Read .aidlc/context/constitution.md when it exists and apply the constitution rule in aidlc-overview.
  3. Find the seams before proposing structure. A project is brownfield from its second instance onwards, so start from the assumption that something in the codebase already does part of what the requirements ask for. For each capability in requirements.md, locate and read the existing code that carries any of it — the scheduler that already fires, the settings shape that already persists, the registry that already dispatches — and name those files in design.md before describing a single new component. Keep it narrow: the seams the requirements actually touch, a handful of files, not a survey. When nothing exists, write that down — "no existing seam" is a finding, and stating it is what separates a genuinely new component from one designed alongside the code that should have absorbed it.
  4. Define architecture. Describe the high-level structure: components, their responsibilities, and how they communicate. Say for each one whether it extends a seam found in step 3 or is new.
  5. Specify interfaces. For each component boundary, define the contract (function signatures, API shapes, data types).
  6. Data flow. Document how data moves through the system — inputs, transformations, storage, outputs.
  7. Design decisions. Record each significant decision with rationale and alternatives considered. Persist accepted decisions as decision entities: aidlc knowledge add --type decision --id <slug> --name "<title>" --description "<rationale>".
  8. Address non-functional concerns. Map performance, security, and accessibility requirements to design choices.
  9. Identify risks. Note technical risks and mitigation strategies.
  10. Produce the task breakdown. For templates that require it (full-feature, quick-feature), write tasks.md in the instance state directory as the final design step — the design is not done until it is actionable. Decompose the design into commit-sized tasks: each one reviewable in one sitting and independently verifiable. One task per line, in this exact grammar:
- [ ] T<n>: <title>
- [ ] T<n>: <title> (AC-1, AC-2)
- [x] T<n>: <title> (AC-3)
- [>] T<n>: <title> (AC-4) (deferred YYYY-MM-DD: <reason>)

Number tasks sequentially (T1, T2, ...) — IDs are never renumbered or reused; a task overtaken by events is deferred with a reason, never deleted. Reference the acceptance criteria each task satisfies where any apply; chore or infrastructure tasks may legitimately have none (the implementation gate surfaces them as warnings, never failures).

Exit Criteria

  • design.md exists with architecture, interfaces, and at least one design decision with rationale
  • design.md names the existing code the change extends, or states that no such code exists
  • Every knowledge-graph symbol the design builds on was checked against the source
  • The design addresses all acceptance criteria from requirements.md
  • For templates requiring it: tasks.md exists and every active acceptance criterion is claimed by at least one task, or the gap is deliberate
  • The user has confirmed the design direction

Guidance

{{context:architecture}} {{context:style-guide}} {{guidance:secure-defaults}} {{guidance:accessibility}}

Security Confirmation

If the design involves:

  • New authentication or authorization flows
  • Data storage of sensitive information
  • External service integrations with credentials
  • Infrastructure provisioning

You MUST flag these explicitly in the design document and note that implementation will require security confirmation before proceeding.

Completion

When exit criteria are met, update phase-design.yaml status to complete and append a transition record to transitions.log.

Changing a completed phase's artifact. Do it only through an amendment — append an ## Amendment <n> — YYYY-MM-DD section to requirements.md with Retires:, Issues:, Reopens: and Reason: bullets, then run aidlc amend <instance> (start with --impact to see what still cites the retired criteria). Editing the artifact directly leaves every gate passing while the requirements and the code disagree.