Topic: Appendix C. Checklists and Templates
Difficulty level: Medium
Estimated study time: 4-6 hours (theory 2 hours, practice 2-4 hours)
Prerequisites: Basic understanding of SDD (Specification-Driven Development) methodology
Experience with version control systems (Git)
Familiarity with Markdown format
Understanding of project documentation structure (requirements.md, plan.md, validation.md)
Experience interacting with AI agents in development
Learning objectives: Independently apply all Appendix C checklists at every stage of the feature lifecycle: from specification to merge request
Create complete merge requests and retrospectives using provided templates without skipping mandatory sections
Formulate minimal prompts for implementation review and replanning that ensure effective AI agent operation
Organize a work session with an AI agent after the /clear command, following the new session checklist
Identify and prevent typical errors: secret leakage, unrelated refactorings, out-of-scope changes
Overview: Appendix C is an operational reference for practical application of the SDD (Specification-Driven Development) methodology. Unlike theoretical chapters, this material is designed for immediate use "in the field" — during active project work. It contains six checklists covering the complete feature development cycle: from specification preparation through implementation to merge and retrospective, as well as four ready-made templates for typical operations with an AI agent. The key value is preventing typical errors that are costly when working with AI agents: loss of context, secret leakage, scope creep, invalid results. The material is aimed at an intermediate level: it is assumed that the reader is already familiar with the basic structure of SDD documentation and is ready to integrate checklists into daily practice.
Key concepts: Pre-specification checklist: Eight mandatory conditions that must be met before starting to write a specification. Checks clarity of goal, audience, work boundaries, stack constraints, verifiable results, roadmap phase, and availability of necessary resources. Critically important: attempting to create a specification without meeting these conditions leads to incomplete or inconsistent requirements that the AI agent will interpret unpredictably.
Pre-implementation checklist: Seven readiness control items before handing off a task to an AI agent. Checks for presence and commit of three mandatory files (requirements.md, plan.md, validation.md), correct context handoff (file references instead of long chat history), clean branch, feature boundary compliance with tech-stack.md, and absence of "Trojan" refactorings. Violating this checklist is the main cause of agent failures.
Pre-merge checklist: Seven quality criteria for final branch verification. Includes verification of mandatory facts from validation.md, explicit listing of failed and deferred facts with justification, review of new hooks and MCP servers, secret leakage check, CHANGELOG.md and roadmap update. This checklist is the last line of defense against poor-quality code entering the main branch.
Merge request template: Standardized MR/PR structure in Markdown format. Contains five mandatory sections: specification (with folder and phase), list of changes, verification facts with checkboxes, unverified/deferred facts, out-of-scope changes, and special instructions for the reviewer. Standardization ensures predictable review and reduces cognitive load.
SDD retrospective template: Five sections for systematic analysis of a completed feature: what the specification described correctly, what the agent inferred on its own, what the check caught, which facts were weak, what to transfer to QWEN.md or specs/, what to remove from the process. The retrospective closes the learning loop and accumulates organizational knowledge.
New session checklist after /clear: Six steps for restoring AI agent context after clearing chat history. Checks reading of base files (QWEN.md/AGENTS.md, mission.md, tech-stack.md), the required feature folder, knowledge of forbidden files, expected verification commands, and stop conditions for research tasks. Without this checklist, the agent works "blindly".
Minimal prompt for implementation review: Standardized prompt for code verification by an agent. Structure: clear, read context, compare with three reference documents, output four categories of results (matches, discrepancies, unverified facts, out-of-scope changes), prohibition on file modification. The minimalism of formulation prevents "creative" interpretation by the agent.
Minimal prompt for replanning: Standardized prompt for preparing the next roadmap phase. Structure: clear, read mission.md, tech-stack.md, roadmap.md, recent specifications and CHANGELOG.md, output list of necessary updates, prohibition on file modification until approval. Ensures consistency of project evolution.
Practice exercises: Name: Specification audit by checklist
Problem: You are handed an incomplete specification for the "PDF report export" feature. Check it against the pre-specification checklist. In the materials: goal described ("users want to save reports"), audience indicated ("all users"), work boundaries not defined, stack constraints not specified, one verifiable result ("file downloads"), roadmap phase not specified, requires integration with external API whose key is not available in local environment. Compile a list of blocking and non-blocking issues.
Solution: 1. Blocking issues: absence of work boundaries (unclear what is in scope and what is not); absence of stack constraints (agent may choose incompatible technology); roadmap phase not specified (violates planning); requires external API with secret unavailable locally (blocks development and testing). 2. Non-blocking but requiring improvement: audience "all users" is too vague — clarify roles; only one verifiable result — add checks for content, format, error handling. 3. Actions: either obtain API access and usage instructions, or exclude integration from the feature, or create a mock for local development.
Complexity: intermediate
Name: Forming a merge request by template
Problem: Work on the "Address autocomplete" feature is complete. Known: specification folder specs/2024-03-15-address-autocomplete/, roadmap phase "Form UX Improvement", changed files src/components/AddressInput.tsx, src/hooks/useAddressAPI.ts, tests/AddressInput.test.tsx. Verified facts: npm run typecheck — passed, npm test — 2 out of 5 failed (known issue with rate limiting on external API). New MCP server added for geocoding. CHANGELOG.md updated. Roadmap not updated as changes are minimal. Compile a complete MR by template.
Solution: ## Specification - Folder: specs/2024-03-15-address-autocomplete/ - Roadmap phase: Form UX Improvement ## What Changed - Implemented AddressInput component with autocomplete - Added useAddressAPI hook for integration with geocoding service - Written unit tests for component ## Verification Facts - [x] npm run typecheck - [ ] npm test (3/5 passed, 2 failed due to rate limiting on external API) ## Unverified or Deferred Facts - Integration tests with real API: deferred, requires test account without rate limiting - Load testing: deferred until production keys received ## Out-of-Scope Changes - None ## What Reviewer Should Check Especially Carefully - New geocoding MCP server: check error handling and timeout - Correct hook operation during rapid input (debounce)
Complexity: intermediate
Name: Diagnosing failure after /clear
Problem: A developer reports: after the /clear command, the AI agent started making changes to the .env file, although this file is explicitly forbidden from modification. The agent also ignored the existing project architecture and proposed an alternative technology stack. Analyze the situation using the new session checklist and compile a correct sequence of actions to restore operability.
Solution: 1. Diagnosis: agent did not read QWEN.md/AGENTS.md (lacks knowledge of forbidden files); agent did not read tech-stack.md (does not know current stack); likely agent did not read the feature folder either (works without context). 2. Correct sequence: execute /clear; command to read @QWEN.md; command to read @mission.md; command to read @tech-stack.md; command to read the required feature folder; explicitly state: .env file must not be changed; explicitly state: technology stack is fixed in tech-stack.md; indicate expected verification commands; for research task — indicate stop condition. 3. Prevention: add explicit rule to QWEN.md "DO NOT modify .env and secret files" with example.
Complexity: intermediate
Name: Detecting hidden refactoring
Problem: In the implementation plan for the "Email notifications" feature, the agent included an item "Refactoring authentication module to use new session storage". tech-stack.md specifies current session storage, which does not conflict with the notifications feature. Analyze the situation using the pre-implementation checklist and determine the correct action.
Solution: 1. Checklist analysis: item "no unrelated refactorings in plan" — NOT met. 2. Justification: authentication module refactoring has no causal connection to email notification sending; changing session storage is a separate feature with its own risks and validation requirements; mixing in one branch violates the principle of atomic changes. 3. Correct action: remove refactoring from this feature's plan.md; if refactoring is genuinely needed — create a separate specification with its own requirements.md, plan.md, validation.md; if refactoring blocks the feature — explicitly document this dependency and obtain approval for scope expansion. 4. Risks of ignoring: increased review volume, impact on unrelated functions, difficulty of rollback if problems occur.
Complexity: intermediate
Case studies: Name: API key leak into specification: incident at a fintech startup team
Scenario: A team of 4 developers uses SDD for developing a payment processing microservice. A senior developer creates a specification for processing integration, including example requests with a real test API key for clarity. The specification is committed to the specs/ repository. The AI agent uses this key in code and logs during implementation. Code passes review and reaches staging.
Challenge: The test key ended up in three places: specs/ (specification), src/config/payment.ts (code), logs/debug-2024-01-15.log (logs). The key had access to the processing test environment with real (though test) cards. Leakage was only discovered during a security audit 3 weeks later. Potential damage: compromise of client test data, processing account blocking, reputational risks.
Solution: Applied the pre-merge checklist, which had previously been ignored due to rush. Implemented: automatic secret checking via git-secrets in pre-commit hook; mandatory checklist item "secrets did not leak into specifications, logs, and memory" with manual verification; specification template with placeholders instead of real keys (API_KEY_PLACEHOLDER); separate secrets.template.md file in .gitignore for local settings; retrospective with QWEN.md update with rule "NEVER include real secrets in examples".
Result: Zero incidents in 8 months after implementation. MR check time increased by 2 minutes, but review time decreased by 15% due to standardization. Team discovered 2 more historical leaks during retrospective audit. Processing provided a separate sandbox without real data.
Lessons learned: A checklist without an enforcement mechanism is useless — automatic checks or blocking code review are needed
Examples in specifications must use explicit placeholders, even if this reduces "clarity"
Retrospectives must record not only successes but also "weak facts" — they indicate systemic gaps
Rules from incidents must migrate to QWEN.md immediately, not "someday"
Related concepts: Pre-merge checklist
SDD retrospective template
New session checklist after /clear
Name: Context recovery after failure: legacy system migration
Scenario: A consulting company is migrating a monolith to microservices with an AI agent. Project lasts 6 months, 47 specifications. At a critical moment, the developer is replaced by a new employee who does not know the project history. During the first session with the agent after /clear, it proposes using an ORM different from the one fixed in tech-stack.md, and starts rewriting existing migrations.
Challenge: The new developer gave the agent a "brief description" of the project instead of file references. The agent did not read tech-stack.md, did not learn about the prohibition on changing existing migrations, did not understand architectural decisions from previous phases. Result: 3 hours of agent work went to waste, existing tests broke, local database ended up in an inconsistent state.
Solution: Strict adherence to the new session checklist after /clear: sequential reading of QWEN.md (with updated project rules), mission.md, tech-stack.md, current feature folder. Explicit indication of forbidden files: "migrations/2024-* cannot be changed — they are applied in production". Using minimal prompt for replanning to understand current roadmap state. Implemented practice: every new participant goes through a "trial session" with mentor observation.
Result: New developer onboarding time reduced from 5 days to 1.5 days. Created onboarding template in QWEN.md with list of "things every new participant must know". Lost agent work became a learning case for the team. Established rule: first request of any new session — always reading base files, no exceptions.
Lessons learned: "Brief description" does not replace structured files — agent loses details and hallucinates
New session checklist is not a formality but a critically important context recovery mechanism
Forbidden files must be listed explicitly and concretely, not in general formulations
New participant onboarding must include practice working with AI agent under observation
Related concepts: New session checklist after /clear
Minimal prompt for replanning
Minimal prompt for implementation review
Study tips: Create a physical or digital "memory card": print all checklists on one A4 sheet and keep in sight during work — tactile presence reduces the likelihood of skipping items
Practice "reverse checklist": take completed MRs from your practice and verify they match the template — this reveals habitual omissions
Record typical errors in a personal "supplementary QWEN.md" — over time you will accumulate a list of additions specific to your project
Use the "first request is always a template" technique: even if the situation seems unique, start with the minimal prompt and modify it — this prevents "creative" agent behavior
Conduct micro-retrospectives: 5 minutes after each feature, without waiting for a formal retrospective — record one thing the agent inferred on its own, and one the specification described inaccurately
Pair learning: find a colleague and take turns playing "developer" and "checklist reviewer" roles — an external perspective catches omissions you don't notice yourself
Adapt templates for your project: copy the MR template into your repository as .github/pull_request_template.md or equivalent — automatic template appearance eliminates the laziness of filling it out
Additional resources: Original Appendix C from the SDD course: Source material on which this guide is based — use as a quick reference in field conditions
Templates for copying: Create in your project files: TEMPLATES/merge-request.md, TEMPLATES/retrospective.md, TEMPLATES/minimal-prompts.md with content from Appendix C
Secret checking tools: git-secrets (AWS Labs), truffleHog, GitGuardian — for automating the "secrets did not leak into specifications" item
Extensions for working with checklists: Markdown Checkbox in VS Code, GitHub Task Lists, Obsidian Tasks — for tracking item completion
Community QWEN.md examples: Search repositories with tag qwen-md or sdd-methodology for inspiration on context file structure
MCP server documentation: Resources on Model Context Protocol for understanding the "new MCP servers were reviewed" item in the pre-merge checklist
Summary: Appendix C is the operational brain of the SDD methodology, turning theoretical principles into concrete actions. Six checklists cover the complete feature lifecycle and protect against typical errors: incomplete specification, agent context loss, secret leakage, scope creep, inconsistent code. Four templates standardize communication and reduce cognitive load. Key principle: a checklist is either fully executed or not executed at all — partial application is worse than absence, as it creates a false sense of security. Successful mastery of the material is measured not by knowledge of items but by automaticity of their application: checklists should become muscle memory, and templates — the default way of working. Regular retrospectives close the learning loop, turning individual experience into organizational knowledge.