Part 11. Second Feature Phase

The second feature phase checks whether the process has become repeatable. The first feature often runs on enthusiasm. The second shows whether you can start clean, maintain boundaries, update the changelog, and not get overwhelmed by the volume of changes.

In AgentClinic, the second phase might be called "Agents and Ailments." It introduces SQLite, tables for agents and ailments, seed data, /agents and /ailments pages, tests, and navigation.

Clean Start Checklist

Before a new feature branch:

git checkout main
git pull --ff-only
git status --short
npm test
npm run typecheck

In Qwen Code:

/clear

Check the roadmap:

Read @specs/roadmap.md.
What is the next uncompleted phase?
Do not modify files.

If there are uncommitted changes, do not start a new phase. Otherwise, changes generated by the agent will be hard to explain.

Creating the Second Phase Specification

Prompt:

Start the next feature phase from @specs/roadmap.md.
Create a feature branch and a specification directory with a date.

Before writing files, ask me exactly three groups of questions:
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 out of scope?

Use @specs/mission.md and @specs/tech-stack.md.
Do not implement code yet.

Answers might look like this:

Boundaries:
Add agents and ailments as read-only. Include list pages and an agent detail page.
No appointment booking or forms yet.

Decisions:
Use SQLite with hand-written migrations. Add fictional seed data.
Use Hono routes and server-rendered components.
Add route and component tests with Vitest.

Context:
Content should be satirical, but implementation should be clear.
Interface must be responsive. No client-side JavaScript.

Cognitive Load and Review Boundaries

The second phase is usually larger than the first. When an agent changes dozens of files in one pass, a human physically cannot process them all — the eye glides over, errors slip through. To avoid drowning in this flow:

• implement task groups one at a time or in pairs;
• make intermediate commits;
• ask Qwen Code to summarize changes by task group;

• use /review if your version of Qwen Code supports the built-in review process;
• do not accept changes that do not align with the specification.

Example review prompt:

/clear
Review the current branch against @specs/2026-05-02-agents-ailments/plan.md
and @specs/2026-05-02-agents-ailments/validation.md.

Focus on:
1. scope creep beyond the phase boundaries;
2. database migration safety;
3. gaps in test coverage;
4. contradictions with @specs/tech-stack.md.

Do not modify files.

Example Task Groups

# Plan — Agents and Ailments

## Group 1 — Database Bootstrap

1. Install better-sqlite3.
2. Add a database connection module.
3. Add a repeatable migration mechanism.

## Group 2 — Domain Schema

4. Add the agents table.
5. Add the ailments table.
6. Add the agent_ailments junction table.

## Group 3 — Seed Data

7. Add fictional agents.
8. Add fictional ailments.
9. Link agents to ailments.

## Group 4 — Routes and Components

10. Add the /agents list page.
11. Add the /agents/:id detail page.
12. Add the /ailments page.

## Group 5 — Tests and Validation

13. Add route tests.
14. Add component rendering tests.
15. Run npm test and npm run typecheck.

Style Decisions Must Also Be in Specifications

If you decide that the brand colors are orange and black, this should not remain only in chat. Record it:

## Visual Direction

- Primary brand colors: orange and black.
- Use color as an accent, not as a full-page theme.
- Pages should remain readable and demo-friendly.

Prompt for Qwen Code:

Update the relevant specifications: AgentClinic brand colors are orange and black.
Then update CSS only where needed.
Do not change the style of unrelated pages.

Bugfix Specification, Not Feature

Not every branch is a new feature. Much of the work is fixing bugs: a user found that the agent list sorts in the wrong order, or that form validation allows an empty message. For such changes, the requirements.md template is a poor fit: the question "what should appear" is secondary here; the main ones are "what is already broken," "why," and "what should not shift during the fix."

In such cases, it is useful to use a separate mode — a bugfix specification. The folder structure is the same:

specs/
  2026-05-12-feedback-empty-message-bug/
    bugfix.md
    plan.md
    validation.md

Only instead of requirements.md, you have bugfix.md with a different set of sections.

# Fix — POST /feedback allows empty message

## Current Behavior

When submitting a form with an empty `message` field, the server returns 302 and saves
a row with an empty message in the `feedback` table. On the /feedback page, such
an entry appears as an empty block.

## Expected Behavior

When `message` is empty, the server returns 400 and the `/feedback/new` page
with the field highlighted and the error text "Message is required". No database
record is created.

## Root Cause Evidence

In `src/routes/feedback.ts`, the POST route accepts the body without calling validation:
the body is passed directly to the insert. This is visible in commit 3a7c1b9 of phase
2026-05-10-feedback-form, where validation was deferred with a `// TODO` comment.

## What Must Not Change

- The GET /feedback route continues to return the list page.
- Existing records in the `feedback` table are not edited or deleted.

- Form field names (`name`, `message`) remain the same.
- The 400 error format matches other project routes.

## Regression Scenarios

- POST with non-empty `message` still saves the record and returns 302.
- POST with empty `name` but non-empty `message` is still saved (if that was the pre-bug behavior).
- The /feedback page shows all previously saved records unchanged.

plan.md for a bugfix is usually shorter: one group for the fix itself, one for a regression test that catches this specific bug.

validation.md must contain a fact-repro: a command or scenario that fails before the fix and passes after. This is the proof that exactly what was broken was fixed:

### F1 — empty message is rejected

- Command: `npm test -- feedback`
- Expectation: POST /feedback with empty message returns 400 and does not create a row
- Owner: automated check
- Status: draft

The key difference between a bugfix and a feature is the mandatory "What Must Not Change" section and mandatory regression. Without them, the agent often "improves" neighboring code and breaks what was working.

If it turns out that the bugfix is turning into a rework — several related bugs, a new schema, a module rewrite — close the bugfix branch, migrate the work to a regular feature branch, and replan. This is not a failure, but a normal signal that the task has grown from "fix" mode into "rework" mode.

Changelog Before Merge

Update @CHANGELOG.md for the work in this branch.
Use a heading with the current date.
Mention the domain schema, routes, pages, tests, and specification updates.
Keep it brief.

Practice

• [ ] Start the second feature branch from a clean main.
• [ ] Create a specification through an interview.
• [ ] Implement groups in parts.
• [ ] Check for boundary deviation.
• [ ] Update the changelog.
• [ ] Merge only after review.

Review Questions

1. Where does cognitive load come from when working with an agent, and what SDD techniques reduce it?
2. Why must style decisions be recorded in specifications?
3. What signs indicate that a phase is too large?