feat(planning): carry universal, overridable design defaults through planning output

TLDR

A short bundled planning reference: one directive line per foundational principle, each cited to a universal primary source with a pointer, an as-of date and a recheck trigger. It states that the principles apply to code, Markdown, skills and instructions, and that the consumer's standards win.
/planning:interview reads the consumer's standards and asks the intent question in every engineering session: is this expected to repeat or vary per client, what the product's existing structure does, and what upstream context says. It captures NFRs under Constraints.
/planning:design names the principles in its design defaults and gains a lifecycle and reversibility section. That section covers one-way vs two-way doors, a greenfield vertical-slice default the user can override, and design investment scaled by subdomain. The handoff gate, plan Step 2 and plan-reviewer check these threads.
The plan template's Review: code-design tag gets a consumer. It loads the consumer's review criteria, else small bundled universal criteria. Introduced, unsynced Duplicated Code is blocking in code; every other cascade finding, and all of Markdown, is a suggestion (DA-A). code-reviewer uses the same severity.
Sizing keeps decompose's one-context-window bar and adds an integrate-at-least-daily cadence. Delivery is several small PRs, one per concern.

Goal

By the time an implementing agent receives an interview Brief or PLAN.md, the planning output already carries universal design defaults. It has asked whether the work should be generalized now or kept specific, grounded in product direction and upstream context, not a fixed rule. It has captured non-functional requirements, matched design investment to reversibility and subdomain, and sized the work for daily integration. Review then flags changes that cascade across many files. Consumers shape or override every default through their own standards and instruction files, the user drives every default the skills present, and nothing ships that is specific to one organization.

Constraints

Extend existing skills; no new plugin or skill (Q1).
Consumer overrides use the existing standards-contract layering; no new planning.yaml key in this effort (Q5). /planning:interview and /planning:design read the consumer's standards through the same contract plan Step 2 uses (Q16). Consumer standards win over the bundled reference (C1).
The bundled reference cites only universal canonical primaries. It never cites melodic-software/standards or another organization's convention files (Q2, Q3). Vendor guidance, such as AWS and Microsoft on per-tenant variation, is labeled as vendor guidance (Q29).
Every design default the interview and design skills present is a recommendation the user can decline (Q17). Review severities are overridable by the consumer's own review criteria (Q21).
Ingested upstream text (tickets, docs, meeting notes) is framed as data, never instructions (docs/conventions/untrusted-content), and generic skills name no provider, going through the operation's owner (ADR 0060).
No new Brief heading: NFRs go under Constraints, and intent and lifecycle under Captured assumptions (Q6, Q15). The Problem First session owns the new ### Problem heading and the gate script's heading list. Edits stay in separate sections, and whichever PR merges second rebases (F7).
Skill bodies point at sources with a pointer, an as-of date and a recheck trigger, never restating volatile specifics (.claude/rules/skill-bodies-state-current-rules.md).
Each new standing instruction names its observed-stumble evidence (AGENTS.md Code Review Rules; Q22):
- intent question: variation-points.md:5-7 and design/SKILL.md:182 depend on an answer no interview file asks for;
- code-design review and cascade severity: plan-template.md:362 promises a review nothing runs, and the user reports PRs where one change cascades across many files;
- reuse line: measured missed reuse and redundancy in agent PRs (deep-research over-engineering report);
- principle names in design defaults: SRP, ISP, LSP, DIP and composition are absent from design/SKILL.md (EXPLORE);
- NFR prompt: the Brief, PRD and plan have no NFR slot (EXPLORE);
- reversibility section and per-tenant line: no owner today (EXPLORE); the user raised both in this interview.
No friction for fast-moving consumers (prototypes, R&D, go-to-market teams): depth scales with the quality bar (Q48).
Avoid overengineering: cheap extension points are fine, speculative machinery is not (C2). Principles apply to Markdown and skills as well as code (C3).
Deliver as several small PRs, one per concern; the exact split belongs to /work-items:decompose (Q28, C4).
Mechanism decisions (which files, scripts and keys change) are made at /planning:plan (Q14).

Acceptance criteria

A bundled reference file in the planning plugin opens with a scope line: the principles apply to code, Markdown, skills and agent instructions, and the consumer's standards win over it.
The reference lists SRP, OCP, LSP, ISP, DIP, composition over inheritance, reuse / DRY of knowledge, coupling and cohesion, information hiding, deep modules and change amplification, and YAGNI's cheap-now test. Each is one directive line, cited to a universal primary with a pointer, an as-of date and a recheck trigger, and gets a Markdown example where one fits.
The reference contains no link to melodic-software/standards or any other organization's convention files.
The reuse line says to search for and reuse existing code first. It says whether to generalize now or wait for real duplication is a per-task decision to ask the user. Its inputs are expected repetition or per-client variation, the product's existing structure, and upstream context. With known repetition or variation, generalize up front, isolating what varies. Otherwise apply the Rule of Three and Metz's wrong-abstraction caution.
The GoF composition wording, the Constantine coupling and cohesion origin, and the Rule of Three are each cited to a fetched primary; where a primary cannot be fetched, the plan-time research picks the best secondary source, the line is labeled secondary, and its recheck trigger is "the cited secondary moves or changes, or a recheck reaches the primary" (Q30).
IF a consumer's standards contradict a bundled default, THEN interview, design and the code-design review apply the consumer's standard and name the default it overrode.
/planning:interview and /planning:design read the consumer's standards through the plan Step 2 contract before applying the bundled defaults.
/planning:interview asks the intent question in every engineering session (Q18, Q34), drawing on connected upstream sources where available; when the request or an upstream artifact already states an answer, the question confirms it rather than asking open. It records the answer under Captured assumptions, so variation-points.md's dependency on that answer is no longer dangling.
The interview prompts NFRs from a short list presented as prompts, not a taxonomy: performance, reliability/availability, security, maintainability, usability, scalability, observability (Q31). It asks for a measurable target only where one matters and records them under Constraints. The list lives in the interview, not the bundled reference, and is labeled judgment (no primary defines it). /planning:design treats an NFR the Brief already captured, observability included, as settled and does not re-ask it.
The intent question and NFR prompt run only in engineering sessions (Q34). Upstream context they draw on is recorded in the Brief as a short summary, never a verbatim quote of private content (Q32). In a private target repo the summary carries a pointer to its source; in a public one it omits identifying titles and URLs of private sources (Q39). Unknown visibility counts as public. The rule covers the auto-resolve source citation and everything published from the Brief, such as PR bodies and issues (Q43).
In an unattended run, the repeat-or-vary part of the intent question is auto-resolved only from the user's own words: the request, or a Brief or PRD the user confirmed. Third-party upstream text informs the recommendation but never settles it, and conflicting sources count as unstated. An unstated answer is recorded blocked with arbiter USER-RESERVED. The existing-structure and upstream-context parts are facts the agent resolves. /planning:design's generalize-now-or-wait question follows the same rule (Q38, Q40, Q41).
In an unattended run, an unstated measurable NFR target and the greenfield architecture style are recorded as captured assumptions, not blocked (Q42).
For bug fixes and refactors, the intent question collapses to a one-line "not applicable?" confirmation (Q45).
/planning:design's design defaults name the reference's principles and point at it.
/planning:design has a lifecycle and reversibility section, with a small reversibility reference beside it:
- Each significant decision is classed as a one-way or two-way door, and one-way doors get deliberate design and an ADR prompt.
- The baseline is the consumer's existing style. Greenfield work gets a vertical slice built to clean internal quality, presented as a default the user can override.
- Design investment scales by subdomain type: core, supporting or generic (Evans, Khononov).
The configurability design default carries the per-tenant line: one shared mechanism, flags for temporary variation, entitlements for per-tier access, and every option has an owner and a removal path. It is cited as vendor guidance.
Plan Step 2's design-default checklist, plan-reviewer and the design-handoff gate check the principle and reversibility threads as resolved or deferred.
Sizing guidance keeps decompose's one-fresh-context-window bar and adds integrating at least daily. It states no hours unit and no one-day cap, and cites small PRs as practice guidance.
A plan phase tagged Review: code-design triggers a fresh-context review at that phase boundary, which:
- loads the consumer's review criteria when present, else small bundled universal criteria;
- rates a many-file cascade as blocking in code and as a suggestion in Markdown, naming the repeated fact or logic, with no numeric file threshold.
code-reviewer rates introduced, unsynced Duplicated Code at the same severity as the code-design review; Shotgun Surgery stays a suggestion (DA-G, approved 2026-10-18).
Markdown and skill authoring guidance points at existing rules rather than adding a new one.
The new defaults scale with the interview's existing quality-bar answer, with no new setting (Q48):
- Prototype, proof of concept or R&D: the intent question is one line; the NFR prompt and the reversibility section are skipped and named as deferred; the code-design review rates a cascade as a suggestion. The reuse line always applies.
- Internal tool: intent and NFRs asked briefly; reversibility only for one-way doors.
- Production: the full set.
- A consumer whose standards favor speed overrides through the standards layering (Q16).
Each behavior change adds one eval case. Each changed plugin gets a changelog fragment (all touched plugins are in fragment mode, scripts/fragment-plugins.txt). Existing evals and gate scripts still pass.

Captured assumptions

The canonical principle sources change rarely, so pointers with as-of dates and recheck triggers keep the reference current. Revisit if a recheck finds a moved or changed source.
Consumer org rules arrive through the consumer's own standards, read by interview, design and plan. Revisit if a consumer cannot override a default that way, which would reopen Q5's planning.yaml key.
The phase-boundary code-design review is the right home for the cascade check. Revisit if /planning:plan finds the dispatch too costly.
Coverage check answered: one unwanted-behavior criterion added (consumer standards contradict a default); no state-driven case applies. Revisit if the user corrects this at confirmation.

Out-of-scope

Syncing melodic-software/standards files into this repo's docs/standards/ (Q4, withdrawn).
A new ### Problem heading, solution-shaped request handling, and /discovery:trace-intent routing (owned by the Problem First session).
A full multi-tenancy design section (Q12) and a full strategic-DDD step; context discovery stays with event-storming (Q23).
A new "SRP for skills" rule (Q13).
/planning:prd changes; its missing NFR section is filed as a follow-up issue (Q27).
Changing plugins outside planning, review and work-items (for example pull-request creation or issue filing) to enforce the privacy rule; this effort changes only the planning-side text they consume (Q46).
Connascence, the Law of Demeter and Beck's simple design in the reference (Q19).

Deferred questions

Q35: Which plugin owns the shared code-design criteria and severity, and how do the others reach them without duplicating them (cite by /plugin:skill, never by path)? Defer until /planning:plan; arbiter: /planning:plan
Q36: When does /planning:plan tag a phase Review: code-design? Defer until /planning:plan; arbiter: /planning:plan
Q37: How deep do interview and design ground in consumer standards, given plan Step 2's scale table and prompts? Defer until /planning:plan; arbiter: /planning:plan
Q47: Unattended edge cases. What counts as the user's own words when a bot or teammate wrote the request? What proves a Brief or PRD was user-confirmed? Does a blocked intent row halt the Brief or let it lock deferred? What happens when design classes the architecture style as a one-way door? How is an unattended NFR assumption recorded? Who classifies a bug fix, and does a refactor that extracts an abstraction skip the one-line collapse? Defer until /planning:plan approval; arbiter: USER-RESERVED
Q44: Where does /planning:design get the NFR prompt list when it runs without an interview Brief, and does an NFR recorded as "no target needed" count as captured? Defer until /planning:plan; arbiter: /planning:plan

Execution shape: per-item PRs

Thanks for the report. Automated triage handed this issue to a maintainer.

Proposed work class: work-class: structural
Basis: automated intake triage; a maintainer confirms or changes it.

_{Automated triage. A maintainer reviews it.}

feat(planning): gate principle and reversibility threads at handoff, …

Close-out for the malleable design defaults plan. All nine items shipped:

Item	Plan phase	PR
#8327	1 (code-design inputs)	#8348
#8328	7 (sizing cadence)	#8382
#8329	1 (code-design mode)	#8388
#8330	1 (code-reviewer severity)	#8395
#8331	6 (phase-boundary dispatch)	#8394
#8332	2 (principle reference)	#8393
#8333	3 (interview defaults)	#8407
#8334	4 (design defaults, reversibility)	#8413
#8335	5 (plan-time checks)	#8419

Phase 8 filed #8322. The approved plan, with phase tags and the one scope change (Phase 5) as shipped:

PLAN.md

Malleable design defaults

Restatement: CONFIRMED (user, 2026-10-18; Q48 quality-bar scaling added and accepted the same day)

Brief

Spec container: github:#8326

TLDR

A short bundled planning reference: one directive line per foundational principle, each cited to a universal primary source with a pointer, an as-of date and a recheck trigger. It states that the principles apply to code, Markdown, skills and instructions, and that the consumer's standards win.
/planning:interview reads the consumer's standards and asks the intent question in every engineering session: is this expected to repeat or vary per client, what the product's existing structure does, and what upstream context says. It captures NFRs under Constraints.
/planning:design names the principles in its design defaults and gains a lifecycle and reversibility section. That section covers one-way vs two-way doors, a greenfield vertical-slice default the user can override, and design investment scaled by subdomain. The handoff gate, plan Step 2 and plan-reviewer check these threads.
The plan template's Review: code-design tag gets a consumer. It loads the consumer's review criteria, else small bundled universal criteria. A many-file cascade is blocking in code and a suggestion in Markdown, and code-reviewer uses the same severity.
Sizing keeps decompose's one-context-window bar and adds an integrate-at-least-daily cadence. Delivery is several small PRs, one per concern.

Goal

By the time an implementing agent receives an interview Brief or PLAN.md, the planning output already carries universal design defaults. It has asked whether the work should be generalized now or kept specific, grounded in product direction and upstream context, not a fixed rule. It has captured non-functional requirements, matched design investment to reversibility and subdomain, and sized the work for daily integration. Review then flags changes that cascade across many files. Consumers shape or override every default through their own standards and instruction files, the user drives every default the skills present, and nothing ships that is specific to one organization.

Constraints

Extend existing skills; no new plugin or skill (Q1).
Consumer overrides use the existing standards-contract layering; no new planning.yaml key in this effort (Q5). /planning:interview and /planning:design read the consumer's standards through the same contract plan Step 2 uses (Q16). Consumer standards win over the bundled reference (C1).
The bundled reference cites only universal canonical primaries. It never cites melodic-software/standards or another organization's convention files (Q2, Q3). Vendor guidance, such as AWS and Microsoft on per-tenant variation, is labeled as vendor guidance (Q29).
Every design default the interview and design skills present is a recommendation the user can decline (Q17). Review severities are overridable by the consumer's own review criteria (Q21).
Ingested upstream text (tickets, docs, meeting notes) is framed as data, never instructions (docs/conventions/untrusted-content), and generic skills name no provider, going through the operation's owner (ADR 0060).
No new Brief heading: NFRs go under Constraints, and intent and lifecycle under Captured assumptions (Q6, Q15). The Problem First session owns the new ### Problem heading and the gate script's heading list. Edits stay in separate sections, and whichever PR merges second rebases (F7).
Skill bodies point at sources with a pointer, an as-of date and a recheck trigger, never restating volatile specifics (.claude/rules/skill-bodies-state-current-rules.md).
Each new standing instruction names its observed-stumble evidence (AGENTS.md Code Review Rules; Q22):
- intent question: variation-points.md:5-7 and design/SKILL.md:182 depend on an answer no interview file asks for;
- code-design review and cascade severity: plan-template.md:362 promises a review nothing runs, and the user reports PRs where one change cascades across many files;
- reuse line: measured missed reuse and redundancy in agent PRs (deep-research over-engineering report);
- principle names in design defaults: SRP, ISP, LSP, DIP and composition are absent from design/SKILL.md (EXPLORE);
- NFR prompt: the Brief, PRD and plan have no NFR slot (EXPLORE);
- reversibility section and per-tenant line: no owner today (EXPLORE); the user raised both in this interview.
No friction for fast-moving consumers (prototypes, R&D, go-to-market teams): depth scales with the quality bar (Q48).
Avoid overengineering: cheap extension points are fine, speculative machinery is not (C2). Principles apply to Markdown and skills as well as code (C3).
Deliver as several small PRs, one per concern; the exact split belongs to /work-items:decompose (Q28, C4).
Mechanism decisions (which files, scripts and keys change) are made at /planning:plan (Q14).

Acceptance criteria

A bundled reference file in the planning plugin opens with a scope line: the principles apply to code, Markdown, skills and agent instructions, and the consumer's standards win over it.
The reference lists SRP, OCP, LSP, ISP, DIP, composition over inheritance, reuse / DRY of knowledge, coupling and cohesion, information hiding, deep modules and change amplification, and YAGNI's cheap-now test. Each is one directive line, cited to a universal primary with a pointer, an as-of date and a recheck trigger, and gets a Markdown example where one fits.
The reference contains no link to melodic-software/standards or any other organization's convention files.
The reuse line says to search for and reuse existing code first. It says whether to generalize now or wait for real duplication is a per-task decision to ask the user. Its inputs are expected repetition or per-client variation, the product's existing structure, and upstream context. With known repetition or variation, generalize up front, isolating what varies. Otherwise apply the Rule of Three and Metz's wrong-abstraction caution.
The GoF composition wording, the Constantine coupling and cohesion origin, and the Rule of Three are each cited to a fetched primary; where a primary cannot be fetched, the plan-time research picks the best secondary source, the line is labeled secondary, and its recheck trigger is "the cited secondary moves or changes, or a recheck reaches the primary" (Q30).
IF a consumer's standards contradict a bundled default, THEN interview, design and the code-design review apply the consumer's standard and name the default it overrode.
/planning:interview and /planning:design read the consumer's standards through the plan Step 2 contract before applying the bundled defaults.
/planning:interview asks the intent question in every engineering session (Q18, Q34), drawing on connected upstream sources where available; when the request or an upstream artifact already states an answer, the question confirms it rather than asking open. It records the answer under Captured assumptions, so variation-points.md's dependency on that answer is no longer dangling.
The interview prompts NFRs from a short list presented as prompts, not a taxonomy: performance, reliability/availability, security, maintainability, usability, scalability, observability (Q31). It asks for a measurable target only where one matters and records them under Constraints. The list lives in the interview, not the bundled reference, and is labeled judgment (no primary defines it). /planning:design treats an NFR the Brief already captured, observability included, as settled and does not re-ask it.
The intent question and NFR prompt run only in engineering sessions (Q34). Upstream context they draw on is recorded in the Brief as a short summary, never a verbatim quote of private content (Q32). In a private target repo the summary carries a pointer to its source; in a public one it omits identifying titles and URLs of private sources (Q39). Unknown visibility counts as public. The rule covers the auto-resolve source citation and everything published from the Brief, such as PR bodies and issues (Q43).
In an unattended run, the repeat-or-vary part of the intent question is auto-resolved only from the user's own words: the request, or a Brief or PRD the user confirmed. Third-party upstream text informs the recommendation but never settles it, and conflicting sources count as unstated. An unstated answer is recorded blocked with arbiter USER-RESERVED. The existing-structure and upstream-context parts are facts the agent resolves. /planning:design's generalize-now-or-wait question follows the same rule (Q38, Q40, Q41).
In an unattended run, an unstated measurable NFR target and the greenfield architecture style are recorded as captured assumptions, not blocked (Q42).
For bug fixes and refactors, the intent question collapses to a one-line "not applicable?" confirmation (Q45).
/planning:design's design defaults name the reference's principles and point at it.
/planning:design has a lifecycle and reversibility section, with a small reversibility reference beside it:
- Each significant decision is classed as a one-way or two-way door, and one-way doors get deliberate design and an ADR prompt.
- The baseline is the consumer's existing style. Greenfield work gets a vertical slice built to clean internal quality, presented as a default the user can override.
- Design investment scales by subdomain type: core, supporting or generic (Evans, Khononov).
The configurability design default carries the per-tenant line: one shared mechanism, flags for temporary variation, entitlements for per-tier access, and every option has an owner and a removal path. It is cited as vendor guidance.
Plan Step 2's design-default checklist, plan-reviewer and the design-handoff gate check the principle and reversibility threads as resolved or deferred.
Sizing guidance keeps decompose's one-fresh-context-window bar and adds integrating at least daily. It states no hours unit and no one-day cap, and cites small PRs as practice guidance.
A plan phase tagged Review: code-design triggers a fresh-context review at that phase boundary, which:
- loads the consumer's review criteria when present, else small bundled universal criteria;
- rates a many-file cascade as blocking in code and as a suggestion in Markdown, naming the repeated fact or logic, with no numeric file threshold.
code-reviewer rates Shotgun Surgery at the same severity as the code-design review.
Markdown and skill authoring guidance points at existing rules rather than adding a new one.
The new defaults scale with the interview's existing quality-bar answer, with no new setting (Q48):
- Prototype, proof of concept or R&D: the intent question is one line; the NFR prompt and the reversibility section are skipped and named as deferred; the code-design review rates a cascade as a suggestion. The reuse line always applies.
- Internal tool: intent and NFRs asked briefly; reversibility only for one-way doors.
- Production: the full set.
- A consumer whose standards favor speed overrides through the standards layering (Q16).
Each behavior change adds one eval case. Each changed plugin gets a changelog fragment (all touched plugins are in fragment mode, scripts/fragment-plugins.txt). Existing evals and gate scripts still pass.

Captured assumptions

The canonical principle sources change rarely, so pointers with as-of dates and recheck triggers keep the reference current. Revisit if a recheck finds a moved or changed source.
Consumer org rules arrive through the consumer's own standards, read by interview, design and plan. Revisit if a consumer cannot override a default that way, which would reopen Q5's planning.yaml key.
The phase-boundary code-design review is the right home for the cascade check. Revisit if /planning:plan finds the dispatch too costly.
Coverage check answered: one unwanted-behavior criterion added (consumer standards contradict a default); no state-driven case applies. Revisit if the user corrects this at confirmation.

Out-of-scope

Syncing melodic-software/standards files into this repo's docs/standards/ (Q4, withdrawn).
A new ### Problem heading, solution-shaped request handling, and /discovery:trace-intent routing (owned by the Problem First session).
A full multi-tenancy design section (Q12) and a full strategic-DDD step; context discovery stays with event-storming (Q23).
A new "SRP for skills" rule (Q13).
/planning:prd changes; its missing NFR section is filed as a follow-up issue (Q27).
Changing plugins outside planning, review and work-items (for example pull-request creation or issue filing) to enforce the privacy rule; this effort changes only the planning-side text they consume (Q46).
Connascence, the Law of Demeter and Beck's simple design in the reference (Q19).

Deferred questions

Q35: Which plugin owns the shared code-design criteria and severity, and how do the others reach them without duplicating them (cite by /plugin:skill, never by path)? Defer until /planning:plan; arbiter: /planning:plan
Q36: When does /planning:plan tag a phase Review: code-design? Defer until /planning:plan; arbiter: /planning:plan
Q37: How deep do interview and design ground in consumer standards, given plan Step 2's scale table and prompts? Defer until /planning:plan; arbiter: /planning:plan
Q47: Unattended edge cases. What counts as the user's own words when a bot or teammate wrote the request? What proves a Brief or PRD was user-confirmed? Does a blocked intent row halt the Brief or let it lock deferred? What happens when design classes the architecture style as a one-way door? How is an unattended NFR assumption recorded? Who classifies a bug fix, and does a refactor that extracts an abstraction skip the one-line collapse? Defer until /planning:plan approval; arbiter: USER-RESERVED
Q44: Where does /planning:design get the NFR prompt list when it runs without an interview Brief, and does an NFR recorded as "no target needed" count as captured? Defer until /planning:plan; arbiter: /planning:plan

Design

Scope: module. Lifecycle: the same principles apply proactively at interview, design and plan, and reactively at the
phase boundary and PR review as a backstop for drift between plan and code.

Module layout

Owner	Owns	Kind
planning `reference/design-principles.md` (new)	principle directives, scope line, consumer-wins line, reuse line	proactive
planning `skills/design/reference/reversibility.md` (new)	one-way/two-way doors, greenfield vertical-slice default, subdomain investment	proactive
planning `skills/interview`	intent question, NFR prompt list, `Quality bar:` and `Intent:` lines	proactive
planning `skills/design`	principle-named design defaults, lifecycle and reversibility section, per-tenant line	proactive
planning `design-handoff`, `plan` Step 2, `plan-reviewer`	principle and reversibility threads gated; plan-time cascade/reuse gap	proactive check
review `skills/quality-gate` `code-design` mode (new)	bundled universal code-design criteria, cascade severity, consumer-criteria loading	reactive
review `agents/code-reviewer.md`	Shotgun Surgery severity aligned with the code-design mode	reactive
implementation `skills/implement`, `implement-dispatch`	phase-boundary dispatch of `architecture`, `security`, `code-design` tags to `/review:quality-gate <mode>`	reactive trigger
work-items `skills/decompose`	one-context-window bar plus integrate at least daily	proactive

Dependency direction: planning cites review and implementation by /plugin:skill only; review never cites planning
files; implementation reads the plan's Review: tags and invokes review. No cycle.

Contracts

Intent: second variant = known | category | speculative; existing structure: <summary>; upstream: <summary or none>
Quality bar: prototype | internal | production
Overrides bundled default <principle> per <standards file>

Intent and quality-bar lines live under the Brief's ### Captured assumptions. Bug fix or refactor:
Intent: not applicable (confirmed). A missing quality-bar line counts as production for review severity, and the
review names that assumption.
Phase-boundary dispatch: architecture → /review:quality-gate architecture; security →
/review:quality-gate security; code-design → /review:quality-gate code-design; concurrency →
/review:quality-gate slice concurrency (existing mode, quality-gate/SKILL.md:65; reports nothing when the
consumer has no concurrency criteria file). The review receives the phase diff, the tag and the
Quality bar: line, with rationale withheld.
Repetition severity (code-design mode and code-reviewer): in code, CRITICAL only for Duplicated Code the diff
introduces, naming the repeated fact or logic and the later otherwise-correct change that would diverge, with no
shared source or sync check keeping the copies aligned; every other repetition or cascade finding (Shotgun Surgery
included) SUGGESTION; Markdown SUGGESTION; quality bar prototype SUGGESTION everywhere; consumer severity
vocabulary and criteria win. (Amended by DA-A after the stress test; was "else IMPORTANT".)
plan-reviewer Design alignment gains: "Does the planned file list or design place one fact or rule in several files,
or build what existing code already does?"

Variation verdicts

Point	Verdict	Containing module	Reason
Consumer standards source	contain	`plugins/planning/reference/standards-contract.md` resolution ladder	already isolated; consumer layouts vary
Consumer review criteria	contain	the code-design mode, loading through the same ladder	consumer criteria win over bundled ones
Upstream context (trackers, docs)	contain	the operation's owner (ADR 0060), framed as data	generic skills name no provider

No abstraction proposed; no abstraction question left to a human.

Conventions followed

plugins/planning/reference/variation-points.md (intent vocabulary, contain-by-default)
plugins/planning/reference/standards-contract.md (resolution ladder, provenance)
plugins/review/context/severity.md (tier tests)
plugins/planning/skills/plan/context/plan-template.md (phase Review: tags)
plugins/planning/skills/plan/context/plan-reviewer.md (review axes)
.claude/rules/skill-bodies-state-current-rules.md, docs/conventions/untrusted-content/README.md,
docs/adr/0060-abstract-provider-details-in-skills-behind-consumer-conventions-and-adapters.md

Plan

Draft (Step 4.7), not yet approved.

Goal. Planning output carries universal, overridable design defaults before an implementing agent gets it; review
backs it up at the phase boundary and the PR.

Standards grounding. Index docs/standards/README.md (standards-contract: 1.0.2; the planning binding is 1.1.0,
so routing is best-effort: index at v1.0.2, contract at v1.1.0, re-run setup). Rows matched for skill and reference
text: reference-dont-duplicate.md (each fact in one place: drives the cite-by-skill ownership and the C-plan-gap
item), simpler-code.md (no new mechanism beyond what a reader acts on), documentation-and-citations.md (pointer,
as-of, recheck records in the principle reference), concise-prose.md, source-authority-tiers.md (primary-first
citations, labeled secondaries). Ambient: AGENTS.md Code Review Rules,
.claude/rules/skill-bodies-state-current-rules.md, .claude/rules/cost-claims.md. Loaded on demand per phase:
plugins/playbooks/skills/skill-authoring/reference/skill-criteria.md, docs/plugin-philosophy.md#instruction-economy.

Resolved deferred questions.

Q35: the review plugin owns the code-design criteria and severity (/review:quality-gate code-design); planning cites
it by /plugin:skill; implementation invokes it. Basis: user approval of design T2, 2026-10-18.
Q36: plan tags Review: code-design on any phase that adds or changes a contract, type, module, or a fact or rule
several files read, skill and instruction Markdown included; omit only for trivial edits. Basis: user, 2026-10-18.
Q37: interview and design use the standards-contract resolution ladder, matched rows only (task surfaces plus
design/architecture concerns); depth follows the quality bar (prototype: ambient only). Basis: user, 2026-10-18.
Q44: the NFR prompt list lives in plugins/planning/skills/interview/context/nfr-prompts.md; design reads it by path
(same plugin) when no Brief captured NFRs; "no target needed" counts as captured. Basis: user, 2026-10-18.

phase_order: composed (default; docs/conventions/planning.yaml sets no phase_order). scaffold_stubs: false
(default). integration_posture: by-kind (no docs/conventions/implementation.yaml key); this is a feature, but
the touched skills grow sections rather than branches, so no reshaping work items beyond each phase's own edits.
No dead-code removal step: the change adds and edits text, and removes no code.

Every phase: one eval case per behavior change in that skill's evals/evals.json; one changelog fragment per touched
plugin (scripts/new-changelog-fragment.sh); merge origin/main first. Each phase is its own PR
(Brief C4); /work-items:decompose turns phases into tracker items.

Phase 1: Code-design review mode [DONE]

Review: code-design
Implements: Design › Module layout rows 6-7; Contracts (C-severity, C-override).

review/skills/quality-gate/SKILL.md: add code-design mode (argument hint, router row, description trigger), and
explicit phase-boundary inputs for every mode: worktree path, base SHA (the previous phase-boundary commit), quality
bar, and a report-only flag; allowed-tools gains the worktree-targeted diff form. With a base SHA no forge lookup
runs. The mode hands the review to review:brief-reviewer in fresh context with the diff, the tag and the quality
bar only, as per-slice.md:10 does (no plan rationale).
New quality-gate/context/code-design.md: load consumer review criteria through the standards contract, else small
bundled universal criteria; apply a contradicting consumer standard and emit
Overrides bundled default <principle> per <standards file>; cascade rule per C-severity naming the repeated fact or
logic, no numeric file threshold, CRITICAL only when the diff introduces the repetition and no shared source or sync
check keeps the copies aligned; exempt contract-restatement markers, registries the repo declares, generated files,
fixtures and rename diffs (DA-A; the exemptions are judgment: no review guide read states them, research gap 1); read the Quality bar: line when the brief carries one (absent = production,
named in the output).
review/agents/code-reviewer.md: Duplicated Code follows C-severity (the CRITICAL case is Fowler's Duplicated Code,
introduced and unsynced; Shotgun Surgery, one change forcing many small edits, stays SUGGESTION). Edit :95 so the
bundled code-design criteria count as the documented rule that licenses escalation for Duplicated Code only, and :103 so a cascade finding naming the
repeated fact and the diverging change may carry Confidence: high when verified at both sites; other smells keep
the advisory default. When its brief carries no Quality bar: line (PR review, fanout), it rates as production and
says so.
Evals as case.yaml dirs under plugins/review/evals/: qg-code-design-cascade (introduced unsynced repetition
CRITICAL), qg-code-design-sanctioned (registry and rename diffs not CRITICAL), qg-code-design-markdown
(SUGGESTION), qg-code-design-prototype (SUGGESTION), qg-code-design-override (override line),
qg-phase-boundary-worktree (review run from an orchestrator against a separate worktree and base SHA). First,
probe that a scaffold_script-written docs/standards/ file is readable in an eval run (the plugin-evals page says
so; unprobed, research gap).
Run /evals:plugin-eval on them with and without the plugin; record the difference in the PR body.
Sanity Check: grep -c "code-design" plugins/review/skills/quality-gate/SKILL.md ≥ 2 and
test -f plugins/review/skills/quality-gate/context/code-design.md.
Sanity Check: after the phase commit, bash scripts/check-changed-skills.sh origin/main exits 0 and
bash scripts/check-affected.sh --tests exits 0 with no SKIP line in its output.

Phase 2: Principle reference [DONE]

Review: code-design
Implements: Design › Module layout row 1; Contracts (scope line, consumer-wins line). Needs Phase 1 merged (cites
/review:quality-gate code-design).

Fetch primaries for GoF composition wording, Constantine coupling/cohesion origin, Rule of Three; where a primary
cannot be fetched, pick the best secondary, label it, and set the Q30 recheck trigger (/discovery:research).
Create plugins/planning/reference/design-principles.md. Line format for each principle:
- **<Name>**: <directive>. Source: <primary>. As of <date>; recheck when <trigger>. Content: scope line (code,
Markdown, skills, agent instructions; consumer standards win, emitting the C-override line); SRP, OCP, LSP, ISP, DIP,
composition over inheritance, reuse/DRY of knowledge, coupling and cohesion, information hiding, deep modules and
change amplification, YAGNI cheap-now test; a Markdown example where one fits; the reuse line (search and reuse
first; generalize-now-or-wait asked per task from intent, existing structure, upstream; known repetition →
generalize up front isolating what varies; else Rule of Three plus Metz's wrong-abstraction caution); a pointer to
/review:quality-gate code-design for review-time criteria; Markdown and skill authoring points at existing rules
(.claude/rules/skill-bodies-state-current-rules.md, /docs-hygiene:extract-ssot), no new rule.
No eval: a reference file with no skill behavior; its readers' evals (Phases 3-5) cover it.
Sanity Check: grep -c "melodic-software/standards" plugins/planning/reference/design-principles.md returns 0.
Sanity Check: grep -cE "^- \*\*(SRP|OCP|LSP|ISP|DIP)\*\*" plugins/planning/reference/design-principles.md
returns 5, and grep -c "; recheck when" plugins/planning/reference/design-principles.md ≥ 11.
Sanity Check: after the phase commit, bash scripts/check-affected.sh exits 0 with no SKIP line.

Phase 3: Interview defaults [DONE]

Review: code-design
Implements: Design › Contracts (C-intent, C-bar, C-override); Module layout row 3. Needs Phase 2.

Create plugins/planning/skills/interview/context/nfr-prompts.md: quality requirements (often called non-functional
requirements, NFRs) as prompts: performance, reliability/availability, security, maintainability, usability
(ISO/IEC 25010:2023 name: interaction capability), scalability (ISO/IEC 25010:2023: part of flexibility),
observability (not an ISO/IEC 25010 characteristic; included by judgment). Labeled judgment; points at ISO/IEC
25010:2023 with as-of and recheck; measurable target only where one matters. Each recorded line under Constraints
starts Quality requirement: so it stays distinct from true constraints (DA-F).
SKILL.md is at 499 of 500 lines (check-skill.sh:534): all new text goes in context/loop.md and
context/nfr-prompts.md, with at most one pointer line in interview/SKILL.md, net zero lines (trim one). Content:
read consumer standards through the ladder before bundled defaults (Q37);
intent question every engineering session (confirm when stated; one line for prototype; "not applicable?" for bug
fix/refactor); record Intent: and Quality bar: lines under Captured assumptions; NFR prompt by quality bar,
recorded under Constraints; upstream summary rules (no verbatim private content; pointer only in private repos,
unknown visibility = public); unattended rules per Q47's answers.
Each new standing instruction names its stumble (Brief Constraints).
Evals as case.yaml dirs under plugins/planning/evals/ (no shared evals.json append, so no conflict with the
Problem First branch): intent asked and recorded; unattended blocked row; prototype one-line collapse; NFR captured;
consumer override line (consumer standards written by scaffold_script as docs/standards/ files; eval runs load
no CLAUDE.md or .claude/ content, even one a scaffold wrote). Judge each new instruction by running the suite on
main's plugin and on the branch's plugin; drop any instruction that does not improve on main. The no-plugin Δ stays
the skill-level check (DA-C).
Sanity Check: grep -c "Quality bar:" plugins/planning/skills/interview/context/loop.md ≥ 1 and
grep -c "Intent: second variant" plugins/planning/skills/interview/context/loop.md ≥ 1.
Sanity Check: after the phase commit, bash plugins/planning/tests/interview-defenses.test.sh and
bash scripts/check-changed-skills.sh origin/main exit 0.

Phase 4: Design defaults and reversibility [DONE]

Review: code-design
Implements: Design › Module layout rows 2 and 4; Contracts (C-intent read, C-override). Needs Phase 3 (reads
nfr-prompts.md and the Quality bar: line).

design/SKILL.md is at 457 of 500 lines: the principle and reversibility content lives in on-demand references,
with one pointer line each in "Design defaults" (DA-C). "Design defaults": name the principles and point at
${CLAUDE_PLUGIN_ROOT}/reference/design-principles.md; the per-tenant line on configurability (one mechanism, flags
for temporary variation, entitlements per tier, owner and removal path; labeled vendor guidance); read standards
through the ladder (Q37); NFRs in the Brief are settled, else read
${CLAUDE_PLUGIN_ROOT}/skills/interview/context/nfr-prompts.md (Q44; the plugin-root form is what
check-skill.sh Check 5 resolves for a sibling-skill file); generalize-now-or-wait follows the interview's
unattended rule.
New "Lifecycle and reversibility" section + design/reference/reversibility.md: one-way/two-way door per significant
decision, ADR prompt for one-way; baseline is the consumer's style, greenfield vertical slice as an overridable
default; investment by subdomain (core, supporting, generic: the three-way split is Vernon's and Khononov's; Evans's DDD
Reference names core and generic only); scaled by the Quality bar: line.
Evals as case.yaml dirs under plugins/planning/evals/: outcome case first (a task whose obvious design puts one
fact in several files; graded on whether the design places it once); one-way door gets an ADR prompt; prototype
skips reversibility and names it deferred; NFR from Brief not re-asked. Judge each new line by running the suite on
main's plugin and on the branch's plugin; drop any line that does not improve on main (DA-C).
Sanity Check: grep -c "design-principles.md" plugins/planning/skills/design/SKILL.md ≥ 1 and
test -f plugins/planning/skills/design/reference/reversibility.md.
Sanity Check: after the phase commit, bash scripts/check-changed-skills.sh origin/main exits 0.

Phase 5: Plan-time checks [DONE]

Review: code-design
Implements: Design › Module layout row 5; Contracts (C-plan-gap, C-tag writer side). Needs Phase 4 (gates its threads).

design-handoff/SKILL.md: gate requires principle and reversibility threads RESOLVED, directional or
TAGGED-DEFERRED (skipped and named for prototype).
plan/SKILL.md Step 2 design-default checklist: same threads; ~~copy Quality bar: into tagged phases' review brief~~.
Scope change 2026-10-19 (review on feat(planning): gate principle and reversibility threads at handoff, plan and plan-reviewer #8419): implementation already passes the plan-level Quality bar: line to
every phase-boundary review (implement/SKILL.md:221), so a per-phase copy was never read. Step 2 now confirms the
Brief carries the line. Step 2 and plan-reviewer also exempt an early-exit design-resolution.md from the thread
audit.
plan/context/plan-reviewer.md Design alignment: the C-plan-gap item and the principle/reversibility threads.
plan/context/plan-template.md phase Review tags: the Q36 rule; concurrency maps to
/review:quality-gate slice concurrency.
Evals as case.yaml dirs under plugins/planning/evals/: dh-missing-reversibility-thread-fails; outcome case
plan-reviewer-flags-spread-fact (a plan whose file list repeats one fact is flagged). Run /evals:plugin-eval
with and without.
Sanity Check: grep -c "one fact or rule in several files" plugins/planning/skills/plan/context/plan-reviewer.md
returns 1.
Sanity Check: after the phase commit, bash scripts/check-changed-skills.sh origin/main exits 0 and
bash scripts/check-affected.sh --tests exits 0 with no SKIP line.

Phase 6: Phase-boundary dispatch [DONE]

Review: architecture
Implements: Design › Contracts (C-tag reader side). Needs Phase 1; runs before Phase 2 so this effort's own tagged
phases get reviewed.

implementation/skills/implement/SKILL.md Step 4 ritual and implement-dispatch/SKILL.md Phase boundaries: for each
Review: concern tag on the phase, invoke /review:quality-gate <mode> in fresh context (architecture,
security, code-design, and slice concurrency for concurrency) with the phase diff, the tag and the
Quality bar: line, worktree path, base SHA and report-only flag, rationale withheld. Sequence: review, fix inside
the phase fence, one re-review scoped to the fixed hunks, then the phase-verifier last. A second CRITICAL on the same
finding goes to DEVIATIONS.md as a blocker and escalates; it never loops.
Evals as case.yaml dirs under plugins/implementation/evals/: a tagged phase dispatches its review before the
commit; an untagged phase does not; a repeated CRITICAL escalates once (unattended). Run /evals:plugin-eval with
and without; record the difference.
Sanity Check: grep -c "quality-gate code-design" plugins/implementation/skills/implement/SKILL.md ≥ 1.
Sanity Check: after the phase commit, bash scripts/check-changed-skills.sh origin/main exits 0.

Phase 7: Sizing cadence [DONE]

work-items/skills/decompose/SKILL.md:71 window-bar row: add integrate at least daily as practice-guidance cadence,
not an estimate (DORA trunk-based development and small batches, Fowler's Continuous Integration: "at least daily"
is the merge floor); no hours unit, no one-day cap; wording agreed with the Problem First session's Work size and
time-units rule before merge (DA-E).
Eval as a case.yaml dir under plugins/work-items/evals/: a slice sized to the window bar is also checked for
daily integration, with no hours estimate.
Sanity Check: grep -c "at least daily" plugins/work-items/skills/decompose/SKILL.md ≥ 1 and
grep -ciE "[0-9]+ hours" plugins/work-items/skills/decompose/SKILL.md returns 0.
Sanity Check: after the phase commit, bash scripts/check-changed-skills.sh origin/main exits 0.

Phase 8: Follow-up issue [DONE]

Search (2026-10-18): gh issue list --state all --search "prd non-functional in:title,body" and "prd NFR" both
returned no match. Filed #8322.

Search before create (/work-items:track search), then file: /planning:prd lacks an NFR section (Q27). On a match,
link instead of filing.
Sanity Check: the search output is recorded under this phase, and the phase lists the filed or matched issue URL.

Test strategy. Behavior is tested by case.yaml eval cases under each plugin's evals/ directory, run with
/evals:plugin-eval. The no-plugin Δ (with-plugin score minus no-plugin score) measures the whole plugin, so each new
instruction is judged by running the same suite on main's plugin and on the branch's plugin; each phase records both
results in its PR body, and an instruction that does not improve on main is dropped. Consumer standards in cases are
docs/standards/ files written by scaffold_script. Outcome cases (a planted spread fact, a planted cascade)
lead; mention checks are secondary. Static gates: scripts/check-changed-skills.sh, scripts/check-affected.sh --tests,
both run after the phase commit. CI runs no eval automatically (eval-browser-dispatch.yml:24 is manual dispatch),
so the per-phase run is the gate.

Alternatives considered.

Planning owns review criteria (design Candidate B): rejected, cross-plugin path. Switch if: the review plugin is
removed from the marketplace.
Code-design tag only, other tags left dead (T1 a): rejected, same cost. Switch if: quality-gate's architecture or
security mode cannot take a phase diff.
One big PR: rejected (Brief C4). Switch if: decompose finds phases cannot merge independently.

Risks and mitigations.

Collision with Problem First on interview text: separate sections; second to merge rebases (F7).
Instruction bloat in interview/design: each line names its stumble; /docs-hygiene:compress audit before PR.
Phase-boundary review cost on every tagged phase: Q36 omits trivial edits; prototype severity stays suggestion.

Blast radius

Blast radius: HIGH
Stress-test needed: Yes — invoking /planning:devils-advocate
Reason: changes standing instructions in four plugins that every consumer's planning and implementation runs read,
and turns a review that never ran into one that can block phase completion.

Stress-test summary

Step 3 plan-reviewer: 0 CRITICAL / 6 IMPORTANT / 6 SUGGESTION, all verified and fixed (review mode first, strict
2→5 chain, concurrency → existing slice mode, real standards index, code-reviewer :95/:103 reconciled, per-phase
evals, post-commit checks).
Step 4 devils-advocate: 9 HIGH / 7 MEDIUM / 2 LOW. Fixed in the plan: runnable case.yaml evals with a with/without
run per phase and outcome cases; SKILL.md line caps (text in context files); quality-gate phase-boundary inputs
(worktree, base SHA, quality bar, report-only, fresh brief-reviewer); bounded review loop with escalation; Phase 6
moved before Phase 2; per-case eval dirs to avoid conflicts with Problem First; Phase 6 sanity grep. Changes to user
answers: listed in "Displaced answers and new external effects" below, awaiting replies.

Displaced answers and new external effects

Id	What the user said	What the plan now proposes	New external effect	Source
DA-A	Cascade in code is blocking; code-reviewer uses the same severity (Q8, Q21, design T6)	CRITICAL only for Duplicated Code the diff introduces with no shared source or sync check (Shotgun Surgery stays SUGGESTION); sanctioned markers, registries, generated files, fixtures and renames exempt; everything else SUGGESTION (no IMPORTANT fallback)	Babysit merge lane blocks on CRITICAL and IMPORTANT (`babysit_classify.py:102`), so a code-reviewer cascade finding becomes a merge blocker in unattended lanes	stress-test finding
DA-B	Missing quality-bar line = production (design default, not asked)	Kept, but under DA-A only the narrow CRITICAL is affected	none beyond DA-A	stress-test finding
DA-C	Design defaults name the principles; design gets a lifecycle and reversibility section (Brief AC)	One pointer line each in SKILL.md; content in on-demand references; each new instruction judged by the same suite on main's plugin vs the branch's, dropped if it does not improve on main	Paid `/evals:plugin-eval` runs, two per phase	stress-test finding
DA-F	NFRs go under Constraints (Q6, no new Brief heading)	Still under Constraints, each line prefixed `Quality requirement:` and the term written "quality requirement (NFR)", because the SEI authors keep quality requirements and constraints separate	none	final research (terminology)
DA-G	`code-reviewer` rates Shotgun Surgery at the code-design severity (Brief acceptance criterion)	The CRITICAL case is Duplicated Code (introduced, unsynced); Shotgun Surgery stays SUGGESTION. Brief wording corrected at handoff	none beyond DA-A	final research (cadence-review)
DA-E	Integrate at least daily (Q20)	Kept, labeled practice-guidance cadence, wording agreed with the Problem First session's time-units rule	Message to the Problem First session	stress-test finding

Execution shape

Dimension	Value
Gates	Phase 1 gates 6; Phase 6 gates 2; then a strict chain 2 → 3 → 4 → 5 (each reads what the previous one adds; no planned breakage)
Shared state	`.changes/<plugin>/` gets one new fragment file per phase (no shared file); `plan-template.md` only in Phase 5
Disjoint streams	{1 → 6 → 2 → 3 → 4 → 5}; {7}; {8}
Worker count	2 at peak (the chain beside Phase 7)

Phase	Surface	Model	Basis
1	sub-agent worker	opus	new mode and severity contract
2	sub-agent worker	opus	research plus per-line judgment
3	sub-agent worker	opus	cross-skill contract, unattended rules
4	sub-agent worker	opus	new section, design judgment
5	sub-agent worker	opus	gate wording across four files
6	sub-agent worker	opus	cross-plugin dispatch contract
7	sub-agent worker	sonnet	one row, closed fence, grep checks
8	main-session	sonnet	tracker writes need search-first judgment and user-visible effects

Open questions

Q47 (USER-RESERVED): presented at approval.

Glossary

Sources: verified research slices (terminology-sources, cadence-review, agent-instructions, each
verification: pass, and earlier slices principles-canon, elicitation-architecture-fit), kept in the planning session's local memory.

Terms

Term	Meaning here	Source
Functional requirement (FR)	What the system must do and how it reacts to inputs.	Bass, Clements, Kazman, Software Architecture in Practice 3rd ed. §4.1
Non-functional requirement (NFR)	Common umbrella for requirements that are not functional; in practice quality requirements, sometimes constraints too. Standard usage, but ISO/IEC 25010:2023 says "quality requirements" and the SEI authors object to "nonfunctional". This plan writes "quality requirement (NFR)".	ISO/IEC 25010:2023 (sample pages); SAiP 3rd ed. p.66
Quality requirement / quality attribute	A measurable or testable property that shows how well the system meets stakeholder needs (Bass et al.); ISO/IEC 25010:2023 groups them into nine quality characteristics.	SAiP 3rd ed. p.63; ISO/IEC 25010:2023
Constraint	A design decision already made, with zero degrees of freedom (a mandated language, a required module). Distinct from a quality requirement.	SAiP 3rd ed. §4.1
SOLID	Martin's five class-design principles below; Martin credits Michael Feathers with the acronym (about 2004).	Martin, InfoQ 2018
SRP	Single Responsibility Principle: a module has one reason to change ("the reasons for change are people").	Martin 2014
OCP	Open-Closed Principle: extend behavior by adding code, not modifying it. Meyer 1988 coined it; the interface reading is Martin's.	Martin 2014
LSP	Liskov Substitution Principle: a property provable of type T holds for any subtype S.	Liskov and Wing 1994
ISP	Interface Segregation Principle: clients are not forced to depend on interfaces they do not use.	Martin 2000
DIP	Dependency Inversion Principle: depend on abstractions; high-level modules do not depend on low-level ones.	Martin 2000
DRY	Don't Repeat Yourself: each piece of knowledge has one authoritative representation (knowledge, not identical text).	Dave Thomas 2003
YAGNI	You Aren't Gonna Need It: no presumptive features; building ahead only when cheap now and it significantly cuts later cost.	Fowler 2015
Rule of Three	Generalize on the third occurrence of similar code, not before.	principles-canon slice
Duplicated Code	Code smell: the same code structure in more than one place. The CRITICAL case in this plan.	Fowler and Beck, Refactoring 2nd ed. ch.3
Shotgun Surgery	Code smell, the opposite of Divergent Change: one kind of change forces many small edits across many places.	Refactoring 2nd ed. ch.3
Divergent Change	Code smell: one module changed in different ways for different reasons.	Refactoring 2nd ed. ch.3
Cascade	This plan's word for a change that must be repeated across many files: Shotgun Surgery, or Duplicated Code being edited.	this plan
One-way / two-way door	Type 1 / Type 2 decision: irreversible, decide slowly / reversible, decide fast.	Bezos, 2015 letter to shareowners (SEC filing)
Core / supporting / generic subdomain	Differentiating and complex / needed but not differentiating / solved, bought or adopted. Evans's DDD Reference names core and generic; the three-way split is Vernon's and Khononov's.	Khononov 2022 ch.1; Vernon IDDD; Evans DDD Reference 2015
DDD	Domain-Driven Design, Eric Evans's 2003 book (copyright 2004), summarized in his 2015 DDD Reference.	DDD Reference 2015
ADR	Architecture Decision Record: a short file recording one significant decision (Title, Context, Decision, Status, Consequences).	Nygard 2011
PRD	Product Requirements Document: a product's purpose, features, release criteria and schedule; a practitioner term.	Cagan 2005
Integrate at least daily	Merge to the main branch at least once a day; a cadence floor, not an effort estimate.	DORA trunk-based development and small batches; Fowler, Continuous Integration (2024)
Δ (delta)	Plugin eval score with the plugin minus the score with no plugin: what the whole plugin contributed.	code.claude.com plugin-evals, "The no-plugin baseline"
Quality bar	The interview's prototype / internal / production answer, recorded as `Quality bar:` in the Brief.	this plan, C-bar
Phase boundary	The point after a plan phase's work and before its commit, where reviews and the phase-verifier run.	implementation plugin
CRITICAL / IMPORTANT / SUGGESTION	Review severity tiers: blocks until fixed / fix before or shortly after merge / optional. The babysit merge lane blocks on the first two.	`plugins/review/context/severity.md:11-13`; `babysit_classify.py:102`
USER-RESERVED	A decision only the user may make; an unattended run records it and does not decide.	interview skill
DORA, CI, PR, SEI, ISO	DevOps Research and Assessment; continuous integration; pull request; Carnegie Mellon Software Engineering Institute; International Organization for Standardization.

Codes used in this plan

Code	Meaning
Q1-Q48	Interview questions in `interview-checklist.md`, the register behind the Brief.
C1-C4 (Brief)	Interview constraints.
F1-F7	Interview facts.
T0-T8	Design threads in the design slice `design-threads.md`.
C-intent, C-bar, C-override, C-tag, C-severity, C-plan-gap (Design)	Contracts in `## Design › Contracts`.
D1	A decision /planning:plan made on its own (an execution-shape tag).
DA-A to DA-E	Plan changes from the devil's-advocate stress test that displace or extend an earlier answer.
Phase 1-8	Plan phases; each becomes one PR.

Handoff to implementation

Approval: approved by the user on 2026-10-18 ("go with recommended" after the final research pass): plan, DA-A to DA-G and Q47 as recommended. Content-control eval arm not adopted (added cost; revisit if branch-vs-main results are ambiguous).

User-approval gates

Q47 answers before Phase 3 and Phase 4 encode the unattended rules.

Execution shape ([EXEC-SHAPE] tagged)

Each phase its own branch and PR via /work-items:decompose. [EXEC-SHAPE D1]

Mechanical work

Merge origin/main before each phase; fragment per touched plugin; scripts/check-affected.sh --tests before push.

Decision	What it changes in the plan	Basis (evidence)	Source
D1 One branch and PR per phase through decompose	Phases become separate tracker items and PRs	Brief Constraints "several small PRs, one per concern"; `work-items/skills/decompose/SKILL.md:71`	plan

Close-out review: PASS. All 9 sub-items are closed by their shipping PRs (#8348, #8382, #8388, #8395, #8394, #8393, #8407, #8413, #8419), and every acceptance criterion was delivered at main 8c85f63.

Departures the user approved:

Three instructions that never beat main in branch-vs-main evals were kept: the design-principles pointer, the settled-quality-requirements line, and the plan-reviewer spread-fact line.
feat(planning): gate principle and reversibility threads at handoff, plan and plan-reviewer #8419 dropped the per-phase Quality bar: copy, because implementation reads the plan-level line.

Durable records: ADR 0078 (the review plugin owns the code-design criteria) and ADR 0079 (phase-boundary dispatch of Review: tags), shipped in #8422.

Review observations:

The design-defaults trigger reads as conditional. fix(planning): apply design defaults on every non-trivial design #8423 tried to fix it, and was closed after its outcome case showed main already writes the Principles thread (1.00 vs 1.00).
The sizing criterion's "small PRs" is covered through the DORA citation rather than by name; no action.

Follow-up filed during the effort: #8322 (PRD quality-requirements section).

feat(planning): carry universal, overridable design defaults through planning output #8326

Description

TLDR

Goal

Constraints

Acceptance criteria

Captured assumptions

Out-of-scope

Deferred questions

Activity

github-actions commented on Oct 19, 2026

kyle-sexton commented on Oct 19, 2026

Malleable design defaults

Brief

TLDR

Goal

Constraints

Acceptance criteria

Captured assumptions

Out-of-scope

Deferred questions

Design

Module layout

Contracts

Variation verdicts

Conventions followed

Plan

Phase 1: Code-design review mode [DONE]

Phase 2: Principle reference [DONE]

Phase 3: Interview defaults [DONE]

Phase 4: Design defaults and reversibility [DONE]

Phase 5: Plan-time checks [DONE]

Phase 6: Phase-boundary dispatch [DONE]

Phase 7: Sizing cadence [DONE]

Phase 8: Follow-up issue [DONE]

Blast radius

Stress-test summary

Displaced answers and new external effects

Execution shape

Open questions

Glossary

Terms

Codes used in this plan

Handoff to implementation

User-approval gates

Execution shape ([EXEC-SHAPE] tagged)

Mechanical work

kyle-sexton commented on Oct 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions