Task: record deviations from approved plans in an append-only section of the plan #33

New issue

Closed

opened 2026-10-03 11:17:08 +00:00 by araemer · 1 comment

araemer commented

2026-10-03 11:17:08 +00:00

Owner

Problem

When the implementation of an approved plan departs from it, during implementation, after review-implementation, or after human PR review, the reason is recorded only in commit messages and the PR description. Two consequences:

The plan in the repo becomes misleading. After spec 001, recipe-app/docs/plans/001-shopping-lists.md still described behaviour the code no longer has (no confirmation for removing items, no controls on a FULL user's own share, a blanket 44 px tap-target rule, a type name that was renamed). Whoever reads the plan later to understand the code is misled; the PR that explains why lives on Forgejo, not in the repo.
review-implementation can't tell an agreed deviation from an accidental one. It checks the code against the plan, so every approved deviation shows up as a finding unless the reviewing session happens to remember the conversation in which it was approved.

Proposal

Like a comment on a Jira task saying "decided against the original plan, because …":

Plan template: an append-only ## Deviations section at the end of every plan. The approved sections stay unchanged (as ADRs do), so it remains visible what was agreed at GATE C. One entry per deviation:
```
### <date> — <plan step / decision id>: <short title>
- Plan: <what the plan said>
- Now: <what was done instead>
- Why: <reason>
- Decided by: <implementation / review-implementation finding / the user in PR review / …>
```
Optionally a closing status of the points flagged at GATE C, and the follow-up issues filed instead of changing the plan.
implement-plan: appends an entry for every deviation it makes (it already has to report them in Step 5), and asks the user to confirm entries that came from their decisions.
review-implementation: reads the section and treats listed deviations as agreed instead of reporting them as findings; it still checks that each listed deviation is actually what the code does.
Escalation rules (unchanged in substance, made explicit):
- A deviation that changes an architectural decision still needs an ADR; the entry links to it.
- A deviation that changes behaviour the spec describes needs a spec update in recipe-platform; the entry says so.

Per the platform's rules, changing the two skills needs ADRs next to them.

First example

recipe-app/docs/plans/001-shopping-lists.md, section "Deviations" (added in recipe-app#47, commit 5861157): 12 entries plus the GATE C status and follow-ups. It was backfilled by the implementing session because only it knew the reasons. Once the convention is settled, it may need reformatting to match.

🤖 Generated with Claude Code

## Problem When the implementation of an approved plan departs from it, during implementation, after `review-implementation`, or after human PR review, the reason is recorded only in commit messages and the PR description. Two consequences: - **The plan in the repo becomes misleading.** After spec 001, `recipe-app/docs/plans/001-shopping-lists.md` still described behaviour the code no longer has (no confirmation for removing items, no controls on a FULL user's own share, a blanket 44 px tap-target rule, a type name that was renamed). Whoever reads the plan later to understand the code is misled; the PR that explains why lives on Forgejo, not in the repo. - **`review-implementation` can't tell an agreed deviation from an accidental one.** It checks the code against the plan, so every approved deviation shows up as a finding unless the reviewing session happens to remember the conversation in which it was approved. ## Proposal Like a comment on a Jira task saying "decided against the original plan, because …": - **Plan template:** an append-only `## Deviations` section at the end of every plan. The approved sections stay unchanged (as ADRs do), so it remains visible what was agreed at GATE C. One entry per deviation: ``` ### <date> — <plan step / decision id>: <short title> - Plan: <what the plan said> - Now: <what was done instead> - Why: <reason> - Decided by: <implementation / review-implementation finding / the user in PR review / …> ``` Optionally a closing status of the points flagged at GATE C, and the follow-up issues filed instead of changing the plan. - **`implement-plan`:** appends an entry for every deviation it makes (it already has to report them in Step 5), and asks the user to confirm entries that came from their decisions. - **`review-implementation`:** reads the section and treats listed deviations as agreed instead of reporting them as findings; it still checks that each listed deviation is actually what the code does. - **Escalation rules** (unchanged in substance, made explicit): - A deviation that changes an architectural decision still needs an ADR; the entry links to it. - A deviation that changes behaviour the spec describes needs a spec update in recipe-platform; the entry says so. Per the platform's rules, changing the two skills needs ADRs next to them. ## First example `recipe-app/docs/plans/001-shopping-lists.md`, section "Deviations" (added in recipe-app#47, commit 5861157): 12 entries plus the GATE C status and follow-ups. It was backfilled by the implementing session because only it knew the reasons. Once the convention is settled, it may need reformatting to match. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

araemer referenced this issue

2026-10-03 11:43:49 +00:00

feat(workflow) Spec status, plan deviations, lettered options, draft PRs per repo #34

araemer commented

2026-10-03 11:58:07 +00:00

Author

Owner

Done in PR 34

araemer closed this issue

2026-10-03 11:58:08 +00:00

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

araemer/recipe-platform#33

No description provided.

Rows
Columns