Study guide: Part 10. Project Replanning

Topic: Part 10. Project Replanning

Difficulty level: Medium

Estimated study time: 3-4 hours (theory + practice)

Prerequisites: Git fundamentals (branching, merging, commits)

Understanding of SDD project documentation structure (mission.md, tech-stack.md, roadmap.md)

Basic experience with Hono framework

Understanding of feature spec concept

Basic knowledge of TypeScript and testing

Learning objectives: Independently conduct a replanning phase between features, creating a separate Git branch and updating project documents

Determine which observations from feature implementation should be codified into rules (QWEN.md), technical decisions (tech-stack.md), validation templates (validation.md), or agent skills

Formulate requests to the AI agent for updating specifications, changelog, and roadmap without implementing new product features

Evaluate roadmap phase size by verifiability and value criteria, avoiding phases that are too broad or too small

Overview: Project replanning is a key phase in the SDD (Specification-Driven Development) methodology, conducted between feature implementations, not within them. It is a moment of deliberate pause when the team captures acquired knowledge, updates project documents, and turns one-time observations into permanent rules. The faster the AI agent generates code, the more important it is to regularly return to the project constitution and correct course while deviation is still small. Replanning answers five critical questions: what did we learn, does the technology stack need updating, is the roadmap still relevant, which checks should become mandatory, and which processes should be automated. Successful replanning creates a flywheel of feedback: every observation from the previous feature triggers a rule update, which reduces the likelihood of the same problem recurring in the next iteration.

Key concepts: Replanning phase: A separate Git branch created after completing a feature, intended exclusively for updating project documents without implementing new product functions. Differs from regular development by prohibiting the writing of code for new features — focus is on reflection and codification.

Codification of observations: The process of turning one-time observations from feature implementation into permanent project artifacts. Four types of artifacts: agent behavior rules (QWEN.md), technical decisions (tech-stack.md), validation templates (validation.md), automatable skills and hooks (.qwen/skills/).

Changelog journal changelog.md: A document maintained with dates that serves as a brief project history for humans and context for the AI agent. Created based on Git history and changes in the current branch, not manually from scratch.

Testing policy: A formalized requirement in tech-stack.md defining the tool (Vitest), the run command (npm test), and the mandatory inclusion of automated checks in feature specifications.

Adaptive design as a project rule: A project-level requirement, not a feature-level one: pages must work at mobile width 375px and desktop 1280px. After codification, it is applied retrospectively to all existing specifications.

Roadmap phase size: A verifiability criterion: a phase should not be too broad ('build all features') nor too small ('add one CSS padding'). An optimal phase has a specific domain goal and 3-5 verifiable tasks.

Feedback flywheel: A continuous improvement model where every signal from feature implementation (repeating agent error, file not found, incorrect test) has a predetermined place to record a response. If no place is found, this is a signal of a missing section in the project structure.

Updating old specifications: The process of bringing completed feature specifications into compliance with new project rules without changing implementation, unless required by updated validation. Preserves historical accuracy: the specification explains which rules were in effect at the time of implementation.

Replanning branch: An isolated line of development (e.g., replanning-after-hello-hono) that starts from main, contains only document changes, and is merged back via merge after checking tests and types.

Practice exercises: Name: Creating a replanning branch and formulating a request

Problem: You have completed the first feature 'Hello Hono' in a Hono + TypeScript project. Observations: the agent twice forgot to run tests before committing; the layout looks poor on phone; the specification had no 'Validation' section; you three times asked the agent to read mission.md before working. Create a replanning branch and formulate a request to the agent to update project documents without implementing new features.

Solution: 1. Create branch: git checkout -b replanning-after-hello-hono

1. Formulate a request with clear constraints:

/clear Read @specs/mission.md, @specs/tech-stack.md, @specs/roadmap.md and the completed Hello Hono feature specification. We are conducting a replanning phase. Do not implement new product features. Propose changes for:

1. testing policy with mandatory pre-commit run;
2. adaptive design as a general requirement (375px/1280px);
3. validation template in feature specifications;
4. automation of reading mission.md via a skill.

Before editing, list the proposed file changes.

1. Verify that the request contains an explicit ban on new features and requires a preliminary list of changes.

Complexity: beginner

Name: Codifying observations into correct artifacts

Problem: After the 'Hello Hono' feature, you recorded 6 observations. Distribute them by artifact type and explain your choice: (a) Agent changed tsconfig.json without permission and broke the build (b) Vitest turned out to be more convenient than manual testing (c) Database migration idempotency on re-run was not checked (d) The request 'generate specification for feature X using template Y' was used 5 times (e) Agent could not find the constants file, though it existed in the project (f) Implementation added a 'status' field not present in requirements.md

Solution: 1. (a) → QWEN.md (agent behavior rule): 'Never change tsconfig.json without human confirmation'

1. (b) → tech-stack.md (technical decision): 'We use Vitest for all tests, npm test runs vitest run'
2. (c) → validation.md (validation template): 'For migrations, check idempotency by re-running'
3. (d) → .qwen/skills/spec-generation/SKILL.md (skill): automate request with feature parameters
4. (e) → QWEN.md (extend 'what to read at start' list): add constants file
5. (f) → requirements.md via replanning branch (backward traceability): retroactively record decision
6. Rationale: choice is determined by the nature of the observation — agent behavior, technical choice, validation form, mechanical repetition, project structure, requirements.

Complexity: intermediate

Name: Evaluating and fixing a roadmap

Problem: Analyze three variants of phase 2 in a roadmap and determine which meets the criteria for a good phase. Suggest fixes for incorrect variants:

Variant A:

Phase 2: build the entire application

• [ ] Add database
• [ ] Make all pages
• [ ] Write tests

Variant B:

Phase 2: add padding-top to Hello Hono header

• [ ] Change CSS

Variant C:

Phase 2: Agents and Ailments

Goal: add basic domain model and read-only pages.

• [ ] Add SQLite schema for agents and ailments.
• [ ] Add initial fictional data.
• [ ] Add /agents and /ailments pages.
• [ ] Add route and component tests.

Solution: 1. Variant A — too broad. Problems: 'entire application' is unverifiable; 'all pages' is not specific; volume of changes hinders human review. Fix: split into 2-3 phases with domain boundaries (e.g., 'Agents and Ailments', 'Requests and Assignments', 'Administration').

1. Variant B — too small. Problems: overhead for branch, code review, and merge exceeds value; no domain meaning. Fix: combine with other CSS tasks into a phase 'Basic layout and navigation' or include as a subtask in a larger phase.
2. Variant C — correct. Verification: specific domain goal ('basic domain model'); 4 verifiable tasks; clear boundaries ('read-only'); measurable result (4 checkboxes).
3. General principle: a phase should be 'verifiable in an evening' and carry domain value.

Complexity: intermediate

Name: Creating CHANGELOG.md and updating via agent

Problem: After completing a replanning branch with changes to tech-stack.md, validation.md, and roadmap.md, formulate a request to the agent for creating or updating CHANGELOG.md. Source data: branch created 2026-05-01, commits include adding Vitest, adaptive design rule, clarification of phases 2-3 in roadmap.

Solution: 1. Request to agent: /clear Create or update @CHANGELOG.md. Use date headings in YYYY-MM-DD format. Rely on Git history of branch replanning-after-hello-hono and changes in current branch. Write briefly and clearly for stakeholders. Each item should be one line starting with a verb.

1. Expected result:

# Changelog ## 2026-05-01

• Added testing policy with Vitest (npm test → vitest run).
• Introduced adaptive design requirement (375px/1280px).
• Clarified boundaries of phases 2 and 3 in roadmap by domain areas.
• Updated feature specification template with 'Mandatory Checks' section.

1. Verification: dates match commits, items are atomic, language is for humans but structured for agent parsing.

Complexity: beginner

Name: Applying the feedback flywheel

Problem: During implementation of the 'Agents and Ailments' feature, the following events occurred. For each, determine which artifact to update, or record that the project structure lacks a section:

1. Agent generated a migration that fails when re-applied to the same database
2. Agent could not find the domain model types file, though it was in /src/types/
3. Human noticed that /agents page does not display correctly on iPhone SE, though tests passed
4. Agent three times asked which API response format to use
5. A real client name accidentally appeared as an example in the feature specification

Solution: 1. Migration fails on re-run → validation.md: new template 'For migrations, check idempotency by re-running' (validation level increases).

1. File not found in /src/types/ → QWEN.md: extend 'what to read at start' list with directory structure; possibly add rule 'before creating types, check existing ones in /src/types/'.
2. Tests passed but real behavior incorrect → validation.md: add fact 'For data pages, check rendering at 375px width in addition to functional tests'; possibly introduce visual validation level (see part 9).
3. Three times asked for API format → .qwen/skills/api-response-format/SKILL.md: codify response standard (JSON, fields, error codes).
4. Real name in specification → QWEN.md: rule 'Never use real client data in examples' + validation.md: check scenario for PII detection (see part 18).
5. Verification: for all 5 cases, a place was found in the existing structure — meaning the structure is adequate. If no place had been found for some observation, this would signal creating a new section.

Complexity: advanced

Case studies: Name: Replanning after the first feature in a medical platform project

Scenario: A team of two developers and a product manager implements SDD for an internal patient management platform. The first feature 'Hello Hono' — a basic welcome page with server-side JSX rendering — is implemented in 2 days using the Qwen Code AI agent. The team is ready to proceed immediately to the 'Patient Registration' feature.

Challenge: The product manager notices that the welcome page displays incorrectly on his iPhone 12 mini (375px width), though everything is fine on desktop. Developer A discovers that the agent forgot to run tests before the final commit and a TypeScript error had to be fixed manually. Developer B three times gave the agent the same request: 'Read mission.md, then generate a specification for feature X using the template from specs/templates/'. The roadmap contains phase 2: 'Implement entire patient module' without detail. The team realizes that without a pause for reflection, the next feature will repeat the same problems.

Solution: The team creates a branch replanning-after-hello-hono and conducts a replanning phase lasting 4 hours. The request to the agent contains a clear ban on implementing new features. Sequence of actions: (1) Agent analyzes the completed Hello Hono specification and proposes changes; (2) tech-stack.md adds Vitest testing policy with mandatory npm test and adaptive design requirement (375px/1280px); (3) validation.md introduces template 'For pages, check rendering at mobile width'; (4) CHANGELOG.md is created with project history; (5) Phase 2 is split into 'Patients: read' (schema, pages, tests) and 'Patients: write' (forms, validation, security); (6) The repeated request is codified into skill .qwen/skills/spec-generation/SKILL.md. Old specifications are updated to new rules without changing implementation.

Result: Time for manual fixes during implementation of 'Patients: read' feature is reduced by 60%. Agent automatically runs tests and checks adaptivity. Specification is generated with one skill call instead of three request iterations. Human review of the phase takes 2 hours instead of expected 6 hours for a monolithic phase. CHANGELOG.md allows a new developer, onboarded after a month, to understand project history in 15 minutes.

Lessons learned: Replanning between features saves more time than it takes by preventing error repetition

Codifying repeated requests into agent skills has a multiplier effect on every subsequent feature

Adaptive design requirement at project level is cheaper than fixing each page separately

Splitting a monolithic phase into verifiable iterations reduces cognitive load for the human reviewer

Changelog is useful not only for humans but also as context for future agent requests

Related concepts: Replanning phase

Codification of observations

Feedback flywheel

Roadmap phase size

Changelog CHANGELOG.md

Name: Failed replanning: consequences of skipping the phase

Scenario: A startup developing a SaaS tool for lawyers uses SDD with the Qwen Code agent. After the first feature 'Hello Hono', the team immediately moves to 'Documents: upload', skipping replanning due to 'investor demo deadline'.

Challenge: In the 'Documents' feature, the agent repeats three errors from Hello Hono: does not run tests (discovered on the last day), generates a page without mobile version (lawyer shows demo from phone — failure), uses a different API response format than in the first feature (frontend breaks during integration). The team spends 3 days on fixes instead of planned 2 days for implementation. The roadmap remains unchanged: phase 3 — 'All other functions' — makes planning meaningless.

Solution: After the demo failure, the team conducts forced replanning in crisis mode. Analysis shows that 70% of problems were predictable from observations in the first feature. Rules are introduced into tech-stack.md retrospectively, but after double work. Old specifications have to be updated with implementation changes, since integration is broken. The skill for specification generation is created, but loses some context due to pressure.

Result: Project falls 2 weeks behind schedule. The team introduces a mandatory replanning phase of 1 day between any features as a hard rule. An internal rule is created: 'No replanning — no branch for next feature'. Positive side effect: a codification culture is formed, the team begins maintaining CHANGELOG.md and regularly updating the feedback flywheel.

Lessons learned: Skipping replanning for speed creates an illusion of time savings

Repeating agent errors are not randomness but a signal of missing rules

Crisis replanning is more expensive than planned: requires changing implementation, not just documents

Hard rule 'replanning is mandatory' protects against short-term pressure optimization

Related concepts: Feedback flywheel

Codification of observations

Replanning phase

Updating old specifications

Study tips: Practice creating replanning branches physically: open terminal, run git checkout -b replanning-after-..., write a meaningful commit. Muscle memory is more important than theoretical understanding for this process.

Keep a personal 'feedback flywheel' as a table: left column — observation from your projects, right — where to record it. Update after every feature.

Practice formulating requests to the agent with an explicit ban on implementation. This is counterintuitive: usually we ask 'do', here — 'don't do, only suggest'.

Create templates for four types of codification artifacts in your editor (snippets or fragments). This will speed up the transition from observation to record.

Check roadmap phase size by the 'verifiable in an evening' rule: if you cannot imagine how to verify everything works in one evening — the phase is too large.

Read CHANGELOG.md before every new feature as context — this way you will understand its value for the agent and for yourself.

Practice distinguishing 'project-level rules' from 'feature-level decisions': adaptive design — project, specific padding — feature. Error here leads to inconsistent specifications.

Use the '5 whys' technique for each observation: why did the agent err? Why not find the file? Why repeat the request? Root causes point to the correct codification artifact.

Additional resources: Original SDD course (parts 1-18): Full context of the Specification-Driven Development methodology with emphasis on working with AI agents

Course part 9 (validation levels): Detailed examination of validation.md templates and raising validation levels upon error discovery

Course part 14 (hooks and skills): Mechanics of creating .qwen/skills/ and automating repeated requests

Course part 17 (defensive hooks): Preventing dangerous commands through automation

Course part 18 (security and secrets): Rules for preventing PII and confidential data leaks in specifications

Vitest documentation: https://vitest.dev — for deep understanding of testing policy setup

Conventional commits guide: Standardization of commit messages, useful for automatic CHANGELOG.md

Keep a changelog: https://keepachangelog.com — international practice of changelog maintenance (adapt to course format)

Summary: Project replanning is a strategic pause between features in SDD, turning chaotic observations into systematic rules. Its goal is not to speed up development, but to prevent error repetition through codification: rules in QWEN.md, technical decisions in tech-stack.md, templates in validation.md, skills in .qwen/skills/. Key practices: separate Git branch with ban on new features, updating old specifications without changing implementation, maintaining CHANGELOG.md as communication for humans and context for the agent, correct roadmap phase size (verifiable in an evening), feedback flywheel with predetermined responses to signals. Skipping replanning creates an illusion of speed and doubles technical debt. Regular codification of 2-3 most frequent observations per iteration forms a self-reinforcing quality system.