Topic: Part 11. Second Feature Phase
Difficulty level: Medium
Estimated study time: 6-8 hours (theory: 2 hours, practice: 4-6 hours)
Prerequisites: Completed first feature phase in the project
Basic Git knowledge (branching, merging, fast-forward)
Experience with relational databases (SQLite)
Familiarity with Hono framework or similar web framework
Basic understanding of server-side component rendering
Experience with Vitest or similar testing framework
Understanding of database migration concepts
Familiarity with Specification-Driven Development (SDD) methodology
Learning objectives: Apply the clean start checklist to prepare for the second feature phase, including repository state verification and absence of pending changes
Formulate second phase specification through structured interview with three question groups: boundaries, decisions, and context
Break down second phase implementation into manageable task groups (5-7 tasks per group) with intermediate commits to reduce cognitive load
Create fix specifications (bugfix.md) with mandatory "What must not change" sections and regression scenarios
Conduct phase boundary validation using targeted review requests, focusing on migration safety, test coverage, and technical stack compliance
Overview: The second feature phase is a critical stage in the Specification-Driven Development methodology that tests whether the development process has become repeatable. If the first phase often proceeds on enthusiasm, the second demonstrates the team's ability to start work cleanly, maintain boundaries, update the changelog, and not get overwhelmed by the volume of changes. In the context of the AgentClinic project, the second phase is called "Agents and Ailments" and introduces significant functionality: an SQLite database, agents and ailments tables, seed data, new pages /agents and /ailments, tests, and navigation. The main challenge of the second phase is cognitive load: an agent can change dozens of files in one pass, and a human physically cannot comprehend them. Therefore, complexity management techniques take center stage in this phase: task grouping, intermediate commits, regular boundary checks, and refusal of changes that do not match the specification.
Key concepts: Clean start: Mandatory procedure before starting a new feature branch: switch to main, update via fast-forward, check for absence of uncommitted changes, run tests and type checks. In the context of working with an AI agent, includes context cleanup (/clear) and roadmap verification. Starting a new phase with pending changes is prohibited — otherwise agent-generated changes will be difficult to explain and integrate.
Specification interview: Method of creating specification through three groups of questions asked to the agent before writing files: (1) Boundaries — which domain entities and pages are included in the phase; (2) Decisions — database, seed data, interface conventions, tests; (3) Context — tone, constraints, risks, and what should remain outside boundaries. This approach prevents implementation leakage into the requirements discussion phase.
Cognitive load: Phenomenon where a human is unable to comprehend dozens of simultaneously changed files. The eye glides over, errors slip through. Mitigation techniques: implement task groups one at a time or in pairs, intermediate commits, requests for change summarization, using /review, refusal to accept changes that do not match the specification.
Task groups: Logical division of phase implementation into 5-7 tasks per group. Example groups for "Agents and Ailments": database startup, domain schema, seed data, routes and components, tests and verification. Each group ends with an intermediate commit and check.
Fix specification (bugfix.md): Alternative specification template for bug fix branches. Includes: current behavior, expected behavior, root cause evidence, what must not change, regression scenarios. Main difference from feature — mandatory sections protecting existing functionality.
Regression scenarios: Checks guaranteeing that the fix did not break working functionality. For form validation fix: POST with non-empty message continues to work, POST with empty name but non-empty message is saved, existing records are not changed.
Fact-repro in validation.md: Command or scenario that fails before the fix and passes after. Example: npm test -- feedback with expectation that POST with empty message returns 400. This is objective verification that exactly what was broken has been fixed.
Changelog before merge: Mandatory CHANGELOG.md update with current date header, brief listing of domain schema, routes, pages, tests, and specification updates. Written concisely, but completeness matters more than brevity.
Visual direction in specifications: Requirement to record style decisions (colors, typography) in specifications, not leave them only in chat. Example: AgentClinic brand colors — orange and black, used as accent, pages remain readable.
Rework instead of fix: Signal to transfer work from fix mode to feature mode: several related bugs, new schema, module rewrite. Normal process requiring closing the fix branch and replanning as a regular feature.
Practice exercises: Name: Clean Start Readiness Check
Problem: You are about to begin the second feature phase "Agents and Ailments" in the AgentClinic project. Perform the complete clean start checklist and determine whether work can begin. Initial data: you are on branch feature/first-phase, have 3 uncommitted files in git status, tests fail with a typing error, in directory specs/ there is a specification draft without a date. Describe the command sequence and the readiness decision.
Solution: 1. git stash push -m 'WIP: first-phase' — save uncommitted changes. 2. git checkout main — switch to main. 3. git pull --ff-only — update without merge. 4. git status --short — check cleanliness (should be empty). 5. npm test — run tests (expected: pass). 6. npm run typecheck — check types (expected: no errors). 7. In Qwen Code: /clear — clear context. 8. Read @specs/roadmap.md and determine the next uncompleted phase. 9. Verify that the undated draft is not an active specification. Decision: work cannot begin until the typing error in main is resolved and the specification draft is formalized. If the typing error exists in main — this is a blocker requiring a separate bugfix branch.
Complexity: intermediate
Name: Formulating the Specification Interview
Problem: You are starting the "Agents and Ailments" phase. Formulate three question groups for the specification interview, based on project context: AgentClinic is a satirical clinic for AI agents, technical stack includes Hono, SQLite, server-side rendering, Vitest, no client-side JavaScript. First phase implemented the main page and feedback form. Roadmap indicates need for agent and ailment directories.
Solution: Group 1 — Boundaries: Which domain entities are included in the phase? (agents, ailments, agent_ailments relationship). Which pages do we implement? (list /agents, details /agents/:id, list /ailments). What is explicitly excluded? (appointment booking, create/edit forms, client-side JavaScript). Group 2 — Decisions: Which database to use? (SQLite with better-sqlite3). How to organize migrations? (manual, rerunnable). Which seed data? (fictional agents and ailments with satirical descriptions). Which tests? (routes on Vitest, component rendering). Which interface conventions? (Hono routes, server-side rendering components, responsive design). Group 3 — Context: What tone of content? (satirical but implementation is clear). What constraints? (no client JS, responsive interface, pages readable for demonstration). What risks? (cognitive load from volume of changes, boundary leakage into forms). What remains outside boundaries? (authentication, admin panel, search and filtering).
Complexity: intermediate
Name: Task Grouping with Cognitive Load Consideration
Problem: Before you is a plan of 15 tasks for the "Agents and Ailments" phase. Tasks: install better-sqlite3, DB connection module, migration mechanism, agents table, ailments table, agent_ailments table, fictional agents, fictional ailments, agent-ailment relationships, /agents page, /agents/:id page, /ailments page, route tests, component tests, run npm test and typecheck. Group tasks optimally for cognitive load reduction and justify the grouping.
Solution: Group 1 — DB Infrastructure (tasks 1-3): Install better-sqlite3, connection module, migration mechanism. Justification: foundation without which schema work is impossible. Verified separately: connection works, migrations are idempotent. Group 2 — Domain Schema (tasks 4-6): Three tables agents, ailments, agent_ailments. Justification: logical schema integrity is visible at once, easier to check relationships. Group 3 — Seed Data (tasks 7-9): Seeders for all three tables. Justification: requires ready schema, provides test data for manual page verification. Group 4 — Routes and Components (tasks 10-12): Three pages. Justification: visual result, can be demonstrated. Risk of cognitive load — possible splitting into subgroups by one page each. Group 5 — Tests and Validation (tasks 13-15): Route tests, component tests, final run. Justification: verification of entire phase, regression detection. Each group — separate commit, between groups — request to agent for change summarization.
Complexity: intermediate
Name: Creating a Fix Specification
Problem: In the "Agents and Ailments" phase a bug is discovered: the /agents page displays agents in creation order (by ID), but alphabetical sorting by name is expected. Meanwhile there is a risk that the "fix" may affect the /ailments page, which already correctly sorts by ailment name. Create bugfix.md with mandatory protection sections.
Solution: bugfix.md: Current behavior — /agents page displays agents in ascending id order (creation order), leading to unpredictable placement during demonstration. Expected behavior — agents sorted by name field in alphabetical ASC order, with Cyrillic support (locale-aware sorting). Root cause evidence — in src/routes/agents.ts query db.query('SELECT * FROM agents') without ORDER BY, visible in phase commit. What must not change — GET /ailments route and its sorting by name ailments, existing records in agents table (resorting without migration), pagination (not yet implemented), response format (HTML page). Regression scenarios — GET /agents returns agents in alphabetical order; GET /ailments preserves its sorting; POST and other methods for agents are unaffected; /agents tests verify order.
Complexity: intermediate
Name: Phase Boundary Validation
Problem: The agent proposed adding to the "Agents and Ailments" phase additional functionality: agent search form by name (client-side JavaScript), administrator page for editing ailments, JWT authentication for admin page. Formulate a review request for the current branch and determine which changes should be rejected.
Solution: Review request: /clear. Review current branch against @specs/2026-05-02-agents-ailments/plan.md and @specs/2026-05-02-agents-ailments/validation.md. Focus on: 1. phase boundary violations; 2. database migration safety; 3. test coverage gaps; 4. contradictions with @specs/tech-stack.md (client-side JavaScript prohibited). Do not modify files. Rejected changes: search form with client-side JavaScript — direct violation of tech-stack.md (no client JS); administrator page — outside phase boundaries (read-only only, no forms); JWT authentication — outside boundaries and phase mismatch (directories are read-only only). Acceptable changes: if search is implemented server-side via query parameter ?q= with Hono processing — discussed, but likely deferred to next phase as not in plan. Decision: reject all three proposals, record reason in specification (boundary violation/technical stack), possibly create specs/backlog/search-agents.md for future phase.
Complexity: advanced
Case studies: Name: AgentClinic: Second Phase Failure Due to Missed Clean Start Check
Scenario: A team of two developers works on the satirical project AgentClinic — a clinic for AI agents. The first phase (main page and feedback form) went successfully, inspired by enthusiasm. The second phase "Agents and Ailments" should introduce SQLite, three tables, three pages, tests, and navigation. Developer A begins work on Friday evening, skipping the git status check.
Challenge: Developer A started a branch from a commit containing uncommitted experimental changes to the feedback form (added priority field, changed validation). Agent Qwen Code, receiving context with these changes, included them in second phase generation. By session end the branch had 47 changed files. During merge attempt it was discovered: (1) feedback form contains priority field not described in first phase specification; (2) database migrations conflict with experimental schema; (3) tests fail due to change intersection; (4) Developer B cannot conduct review — eye glides over 47 files, errors slip through.
Solution: The team applied emergency protocol: 1. Separate branch emergency/clean-state created from clean main. 2. Second phase specification recreated through interview with three question groups. 3. Implementation split into 5 task groups with strict limit: no more than 7 tasks per group, intermediate commit mandatory. 4. Ban on working with agent after 20:00 introduced — cognitive load is incompatible with fatigue. 5. /review check added after each group. 6. Uncommitted feedback form changes formalized as separate feature in backlog.
Result: Second attempt took 3 working days instead of one Friday evening session, but the result was: (1) 23 files instead of 47 — manageable volume; (2) all tests pass; (3) merge went without conflicts; (4) review took 45 minutes instead of impossibility; (5) 2 migration errors found at group check stage, not after merge. Project received stable base for third phase.
Lessons learned: Pending changes — blocker for phase start, not a formality. git status --short check must be zero.
Cognitive load from 40+ files makes review physically impossible. Groups of 5-7 tasks with intermediate commits — not optimization, but necessity.
Time of day affects ability to control the agent. Work with large phases requires fresh state.
Agent amplifies existing chaos, but does not create order itself. Clean start is human responsibility.
Related concepts: Clean start
Cognitive load
Task groups
Specification interview
Name: AgentClinic: Successful Application of Fix Specification for Form Validation
Scenario: After merging second phase "Agents and Ailments" a user discovered that the feedback form from first phase allows empty messages. Server returns 302 and saves empty string to feedback table. Team decides not to mix fix with third phase, but apply fix specification.
Challenge: Fix seems simple (add validation), but risks exist: (1) agent may "improve" adjacent form code, breaking style or logic; (2) changing response from 302 to 400 may affect client-side handling if any; (3) existing empty records in table require decision; (4) 400 error format must match other project routes.
Solution: Branch 2026-05-12-feedback-empty-message-bug created with fix specification: bugfix.md with sections for current/expected behavior, root cause evidence (deferred validation with TODO in commit 3a7c1b9), what must not change (GET /feedback, existing records, field names, 400 format), regression scenarios. plan.md contains two groups: validation fix and regression test. validation.md includes fact-repro: npm test -- feedback with expectation of 400 for empty message. Agent explicitly forbidden to change page style, add client-side validation, modify feedback table.
Result: Fix took 2 hours instead of potential days debugging side effects. Regression test caught agent's attempt to change name field handling (make it required) — change rejected as boundary violation. Existing empty records left unchanged (decision: separate data cleanup task, unrelated to bug). 400 error format matched /agents route thanks to explicit specification.
Lessons learned: Fix specification is more expensive than quick fix: 30 minutes of writing saves hours of regression debugging.
"What must not change" section — main tool for protection against agent "improvements".
Fact-repro in validation.md gives objective readiness criterion, independent of human judgment.
Fix growing into rework should be recognized early and replanned as feature — this is not failure.
Related concepts: Fix specification (bugfix.md)
Regression scenarios
Fact-repro in validation.md
Rework instead of fix
Study tips: Practice clean start as ritual: perform full command set before every agent session, even if "yesterday everything was fine". Automate via shell alias.
Keep personal cognitive load journal: record after how many files your eye starts to "glide". Individual threshold is usually 15-25 files — use it as limit for task group.
Create specification templates in your editor: snippets for requirements.md, bugfix.md, plan.md, validation.md. Time saved on formatting increases time for thinking.
Practice formulating "What must not change" even for features, not only bugfixes — this develops boundary protection skill.
Use Git visually: git log --graph --oneline --all for understanding branch structure, git diff --stat for estimating change volume before commit.
Conduct self-review before agent request: read your specification aloud — unclear spots will become obvious.
Study others' specifications: analyze course examples, identify structure, compare with your own attempts.
Practice rejection: when agent proposes an "improvement", formulate refusal reason by specification, not by intuition — this strengthens discipline.
Additional resources: Git branching documentation: https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging — fundamentals for understanding clean start and fast-forward
better-sqlite3 documentation: https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md — API for working with SQLite in Node.js
hono documentation: https://hono.dev/docs/getting-started/basic — web framework used in project
vitest documentation: https://vitest.dev/guide/ — testing framework for routes and components
Database migrations guide: https://flywaydb.org/documentation/concepts/migrations.html — concepts of rerunnable migrations
"Specification-driven development" course: Course source materials, parts 1-10 — for understanding context of first phase and methodology evolution
Interactive Git trainer: https://learngitbranching.js.org/?locale=en_US — visual learning of branching for clean start preparation
AgentClinic project specification templates: specs/templates/ in project repository — ready blanks for requirements.md, bugfix.md, plan.md, validation.md
Summary: The second feature phase is an exam on development process repeatability. It differs from the first phase by critical requirement of cognitive load management: agent generates more changes, and human must maintain control. Key practices: clean start as impossible without verification, specification through structured interview with three question groups, task grouping with intermediate commits, fix specification with protection of existing behavior, boundary validation before merge. Second phase success is measured not by speed, but by predictability: review is possible, tests pass, merge is clean, changelog is current. Second phase failure is usually result of missed clean start or acceptance of unverified changes. SDD methodology in second phase transitions from "make it beautiful" to "make it so that third phase does not suffer from second phase consequences".