SDSection 5 →

Section 4

AI Understanding: Clarity Before Code

Ensure AI comprehensively understands a feature before coding — shape-spec, Clarification Gate, constitution.md, living docs, and Tier Two approval gates.

"What does the spec say should happen — not what does the code happen to do.

SDD Learning Path — 3D Journey

Drag to orbit · Click nodes to explore · Follow the path from shape-spec to verify

Loading 3D journey...

Core Topics

shape-spec Simulator

Structured conversation — answer each phase before coding.

Phase 1: Frame

What problem does this solve — for whom?

Approval Gates — Tier Quest

Choose: Proceed · Ask First · Block

Round 1/6Score 0
Tier One
Tier Two
Tier Three

Add zod as a new dependency for form validation

Minimal Living Docs Checklist

After implementation, living docs must reflect what shipped. Use this gate before merge — alongside the Ready for Plan Checklist you passed earlier.

Minimal "Living Docs" Checklist

  • requirements.md (or shaped spec) matches what you actually built.

  • plan.md / architecture notes describe the system as implemented.

  • tasks.md checkboxes done and traceable to requirements.

  • Tests, build, lint, or recorded acceptance proof — not “looks fine.”

Complete before merge: spec, plan, tasks, and verification must match reality.
Documentation maintenance

Documentation Files

FileAudiencePurpose
README.mdHumanProduct overview — what this project is
requirements.mdHuman + AIFeature intent — our SPEC equivalent
constitution.mdHuman + AITeam rules — consistency vs flexibility
tasks.mdHuman + AIAtomic work units with verification
AGENTS.mdAIOperational rules — commands, boundaries, structure

Practical Takeaways

  1. 1shape-spec before code. Structured conversation prevents AI misassumptions.
  2. 2Write requirements with EARS patterns — predictable syntax AI and humans parse the same way.
  3. 3Clarification Gate: zero open items in requirements.md — decisions documented, clarity locked in.
  4. 4Ready for Plan Checklist: measurable success, explicit roles, errors, data lifecycle, and DO NOT constraints.
  5. 5constitution.md balances org consistency with project flexibility.
  6. 6Document exact commands — npm run build, not 'make sure it works.'
  7. 7Minimal Living Docs Checklist: spec, plan, tasks, and verification evidence before merge.
  8. 8Tier Two approval gates: dependencies, schema, public API — human verifies first.
  9. 9Living docs evolve with the project. If it is not in git, it does not exist.

constitution.md

Consistency vs flexibility — org rules and project rules.

Open constitution

Approval gates

Tier One · Tier Two · Tier Three decision guide.

Tier system