← Library02 AI Assistant

ai · agentic-engineering · workflow

Spec Map Build Prove Learn

02 AI Assistant/Spec Map Build Prove Learn.md

Spec Map Build Prove Learn

This is the default workflow for substantial AI-assisted coding. It replaces a fragile prompt → code → bug → more prompts spiral with bounded work and evidence.

flowchart LR S[SPEC] --> M[MAP] M --> B[BUILD] B --> P[PROVE] P --> L[LEARN] P -- failure evidence --> B L -- durable guidance --> S

1. SPEC — define the product outcome

A usable specification answers:

  • WHO has the problem?
  • WHY does it matter?
  • WHAT observable outcome is required?
  • RULES constrain implementation or behavior?
  • NOT WHAT is deliberately out of scope?
  • DONE means what evidence exists?
WHO: [users]
WHY: [problem/value]
WHAT: [behaviors]
RULES: [stack, contracts, constraints]
NON-GOALS: [explicit exclusions]
DONE: [tests, typecheck, build, browser evidence]

Changing a specification before implementation is cheap. Correcting dozens of files after vague direction is expensive.

2. MAP — inspect before editing

The agent reads project guidance and repository structure, then returns:

  1. Existing architecture and relevant flows
  2. Affected files/modules
  3. Contracts and invariants
  4. Implementation sequence
  5. Risks and unknowns
  6. Verification plan
Read the product brief, repository instructions, and relevant code. Do not edit yet. Map the existing behavior, affected modules, contracts, risks, and verification plan. Flag assumptions that need evidence.

Permission envelope

Define an explicit boundary for each task:

CAN TOUCH: [files/modules/tests]
DO NOT TOUCH: [auth/payments/schema/shared infrastructure]
Before editing: explain root cause or intended mechanism and list affected files.
After editing: run checks, summarize the diff, and report remaining risks.

This prevents context pollution and unrelated architectural drift.

3. BUILD — one vertical slice

A vertical slice is small but end-to-end. It should cross only the layers required to deliver one user-visible behavior.

Implement only [one outcome] end-to-end. Stay inside [permission envelope]. Preserve existing behavior outside the spec. Add or update relevant tests. Do not perform unrelated refactors.

Backend: contract-driven

Define request, validation, business invariants, persistence behavior, response, and valid/invalid tests. Correctness is demonstrated with contracts and automated evidence.

Frontend: perception-driven

A successful build is not sufficient. Inspect the running interface and verify:

  • Loading, empty, error, and success states
  • Responsive/mobile layout
  • Keyboard operation and accessibility basics
  • Validation messages and interaction flow
  • Console and network errors
  • Visual evidence from the browser

4. PROVE — ask for evidence, not confidence

Prove the specification is satisfied. Return exact commands executed, check results, browser states inspected, a focused diff summary, confirmation that boundaries were respected, and remaining risks. Do not substitute “should work” for evidence.

Review in this order:

  1. Is the specification satisfied?
  2. Did relevant verification pass?
  3. Were permission boundaries respected?
  4. Is the diff safe and narrowly scoped?

Harnessed self-correction

When a check fails, let the agent inspect the failure, identify the root cause, fix without weakening expected behavior, and rerun the relevant checks. Stop after repeated failure and revisit assumptions.

5. LEARN — persist the improvement

Save stable corrections in project guidance, tests, schemas, types, or a reusable skill. Do not rely on chat history as memory.

  • Repeated rule → repository agent instructions
  • Repeated procedure → playbook or skill
  • Behavior guarantee → automated test/contract
  • Architecture choice → decision record
  • General lesson → evergreen vault note

Recover from a prompt spiral

  1. Stop editing.
  2. Inspect the diff and current failures.
  3. Identify the violated assumption or missing context.
  4. Revert only the bad scoped changes safely.
  5. Correct the specification/context.
  6. Restart with a smaller vertical slice.

Capability ladder

  1. Prompt — tell the agent once
  2. Project guidance — teach the repository
  3. Skill/playbook — teach a reusable workflow
  4. Tools — provide controlled actions and live evidence
  5. Delegation — use bounded parallel work only after one-agent reliability

The goal is not an agent that writes more code. The goal is an environment where good code is repeatedly produced and proven.

Source

  • Kyaw Ko Ko Tun, Agentic Fullstack Development webinar, 29-slide PDF supplied by the vault owner, 8 August 2026.

Knowledge connections