Developing with understanding

Developing with Understanding

Make each testable vertical slice something the user can explain, predict, and modify; scale ceremony to risk.

This specialized workflow governs code-design and understanding tasks. When brainstorming or writing-plans also triggers, it supersedes them; do not stack. Use a generic workflow only by explicit user request or higher-priority instruction, confined to the current slice without duplicate preview, approval, or review. Combine applicable testing, debugging, security, and verification skills.

Choose depth

• Low: Local, reversible, mechanical, established pattern. Implement, verify, teach briefly, ask one lightweight check.
• Medium: New use case, several layers, unfamiliar behavior. Preview one slice; implement, explain, ask 1–3 questions.
• High: Boundary, auth, payment, concurrency, migration, irreversible state, or integrity risk that is cross-boundary, irreversible, or high-loss. Routine local uniqueness enforced by one database may remain Medium. Compare 2–3 options, model success/failure, approve, ask 3–5 questions.

Highest signal wins: any high signal means high; any medium signal means at least medium. Uncertainty may raise depth. Urgency or broad authorization (“go ahead,” “just implement”) cannot lower it. Announce depth/reason; keep low brief.

Run the loop

1. Explore. Learn purpose, constraints, and success from code. Ask one question only if evidence cannot answer.
2. Frame. Define one observable behavior and verification; leave later work directional.
3. Preview. Skip low. Medium: smallest realistic interface/flow/test/response plus failure. High: compare 2–3 options, recommend one, show cross-boundary sample/invariants. Use real names.
4. Approve. After the actual preview, get focused approval before medium/high implementation. Broad authorization is not preview approval. Persist the approved spec before editing code; require no large document.
5. Implement. Build only the slice with test/debug discipline. Avoid future infrastructure and unrelated refactors. Revise the preview if code invalidates it.
6. Verify. Check against the preview; report behavior, deviations, actual scope growth, risk. Teach only verified code.
7. Teach live. After verification, start a chat session in the user's language. Explain verified what/why, request/control/data flow, structure, representative boundary/code, decisions, and fragile assumptions. Prefer a concrete walkthrough over a file list; invite questions.
8. Recall interactively. Ask open-book free response one at a time: low 1 lightweight check; medium 1–3; high 3–5. Test impact, failure, and alternatives rather than trivia. Wait for the user's answer. Assess correct ideas, gaps, and wrong models against code evidence; re-explain only the gap and answer their questions. After any materially wrong model, require a targeted re-check; remediation questions do not count toward the depth range. Do not reveal the answer with the question.
9. Close understanding. After the required answers are satisfactory, ask what remains unclear, resolve it, summarize the corrected mental model, and update the understanding record. Only then call the loop complete or choose the next slice.
10. Continue. Only if work remains, choose the next slice from verified code and understanding; otherwise stop.

High finished-form preview: concurrent inventory reservation

• Options: conditional update, row lock, distributed lock. Recommend the first: smallest DB-enforced invariant.
• Interface: POST /reservations {"sku":"A1","qty":2} → 201 {"reservationId":"r7","remaining":0}.
• Boundary/invariant: API → ReservationService → Inventory DB. Conditional decrement (available>=2) and insert commit together; stock never goes negative.
• Failure mapping: no updated row → 409 OUT_OF_STOCK; commit error → rollback, 503, no stock loss.
• Test: two concurrent requests for the last two units produce one 201, one 409, stock 0.
• Approval: “Approve this conditional-update design and contract for the slice?”
• Prediction: 1) “If both requests initially read two available, why can only one succeed?” 2) “What breaks if the decrement and reservation insert are not one transaction?” 3) “Why is a distributed lock not the final invariant?”

Persist every loop

Maintain two linked repository documents per slice. Follow existing conventions; otherwise use the same date and slug in:

• docs/specs/YYYY-MM-DD-<slice-slug>.md
• docs/understanding/YYYY-MM-DD-<slice-slug>.md

Specification: Preserve the implementation contract independently from the later explanation. For Low, write a compact spec after Frame without adding an approval gate. For Medium/High, write it after focused approval and before implementation. Record context/depth, problem and goal, scope/non-goals, approved contract or flow, success/failure, invariants, acceptance criteria/tests, and High options/decision. If code facts require a material change, revise the spec and regain focused approval before continuing; never rewrite it afterward to hide a deviation.

Understanding record: Create it after verification and link the spec instead of repeating its approved contract. Record only actual changes and representative code, deviations, verification commands/results and remaining risk, the verified what/why/flow/boundaries/decisions/fragile assumptions, live recall questions and assessment, user questions, corrected model, and the next slice only if work remains. Use awaiting-recall while the chat session is pending or active, complete after successful closure, and education-opted-out only after an explicit waiver.

Keep Low documents minimal. Leave no placeholders, duplicate prose, secrets, or sensitive payloads. Treat both files as completion outputs and skip them only when the user explicitly opts out.

Guardrails

• Low work needs no preview or approval gate, but still gets a brief live explanation and one lightweight check.
• Implementation is incomplete while required verification or understanding remains.
• Repository documents support the live understanding session; they never replace it. Asking questions without waiting for answers, putting questions only in the record, or posting a completion summary before assessment does not finish a loop.
• Urgency, brevity, broad “done,” fatigue, or the existence of written questions is not an opt-out. If the user defers, keep awaiting-recall and do not call the loop complete. Skip only when the user explicitly waives live teaching after it is offered; record education-opted-out.
• High pre-implementation responses cannot stop at prose options or promised questions: show a concrete interface/call contract, key invariant, failure mapping, focused approval prompt, and 3–5 scenario-specific prediction questions for post-verification use.
• Even while blocked, a High preview must state this future order: after verification passes, first explain verified what/why/flow/boundaries, then ask the listed 3–5 scenario-specific prediction questions. Do not merge the live teaching explanation into the quiz.
• Scope growth is never required; report only actual growth.