docs(planning): fix plan Step-2 design-axes leak (#265)

[kyle-sexton]

Summary

plan's Step 2 re-derived design inline despite the skill's own SSOT rule at plugins/planning/skills/plan/SKILL.md ("/planning:plan consumes design artifacts — do not re-derive design inline when design-significant"). Two spots leaked into /planning:design territory: the design-default axes walk (Emit-checklist paragraph) and build-technique selection (Step 2). This restates both as consume/audit, not derive, keeping plan a thin consumer.

Fix

Doc-only, one skill file plus version/changelog.

• Design-default axes walk → audit against the plan. Reworded from "also walk the design-default axes during Step 2" to "walks its design-default checklist against the plan — confirming the plan reflects the design artifact's resolved threads rather than re-deriving the axes inline." This deliberately splits the six original items by ownership rather than blanket-routing them:
  • configurability / extension points / observability / testability → design threads owned by /planning:design's "Design defaults" (design/SKILL.md) — audit that the plan carries their resolutions.
  • type-collaboration shape → design's Phase 3 type modeling.
  • magic-literal hygiene stays plan's own review check (it is a code-review/quality concern, not design) — the pre-existing "against the consuming project's own review conventions" clause already covers it.
  • Aligns with design-handoff/SKILL.md's existing handoff language: "/planning:plan next walks its design-default checklist against the plan" — the two skills now agree that this is an audit step.
• Build-technique selection → route design/feasibility uncertainty upstream. The issue named this too. It does not violate the SSOT rule the way the axes walk did (spike-vs-tracer-bullet is de-risking sequencing, not re-deriving types/contracts/topology), so it was not gutted to "audit-only." Instead the discriminating branch is pointed upstream: a design / viability / raw-feasibility unknown resolves via /planning:design (or a throwaway /prototype:pressure-test spike), and plan consumes that outcome; the kept-slice integration sequencing (tracer bullet / walking skeleton) remains plan's own call. Integration-first phase ordering (next paragraph) still coheres — it keys off "the kept branch."

Verification

All repo validators run against the change, real output:

• markdownlint (.markdownlint-cli2.jsonc) on both changed docs: Summary: 0 error(s).
• scripts/check-changelog-parity.sh --check-bump origin/main: "Every plugin whose version changed vs origin/main has a '## []' CHANGELOG.md entry."
• scripts/validate-plugins.sh: "All plugin manifests and the catalog validated."
• scripts/check-skill-portability.sh origin/main: "No unexcused coupling tokens in 1 skill file(s)."
• scripts/check-silent-skips.sh: "No silent prerequisite skips found."

Duplication removed — the axes SSOT is confirmed to live in design, and plan no longer restates it as a derivation:

$ grep -rn "configurability" plugins/planning/skills
design/SKILL.md:135:   ...design-default gaps (configurability, extension axes, observability, testability)...
design/SKILL.md:178:   Design defaults ... configurability, extension points, observability, or testability...
design-handoff/SKILL.md:39: ...`/planning:plan` next walks its design-default checklist against the plan
plan/SKILL.md:35: ...design threads owned by `/planning:design`'s "Design defaults" ... audit that the plan carries their resolutions, don't re-open them here.

plan/SKILL.md:35 now points at design's ownership instead of enumerating the axes as its own derivation step.

Closes #265

Related

• Issue docs(planning): fix plan (ex-architect) Step-2 design-axes leak #265 (docs(planning): fix plan (ex-architect) Step-2 design-axes leak).
• Origin: skill-name audit + interview, contract at docs/topics/shadowed-skill-renames/PLAN.md (PR docs: codify skill-naming grammar and cross-plugin reference rules #256).
• No open PR touches plugins/planning/ at dispatch, so no serialization / do-not-merge needed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01K1V3gkrfSf75isB8MiDy3o

[claude]

Claude finished @kyle-sexton's task in 45s —— View job

---

Security Review

• Gather context
• Review PR diff
• Read changed files
• Assess security findings
• Post final review

---

No security issues found.

This PR is documentation-only — three files changed, all editorial:

File	Change	Security surface
plugins/planning/.claude-plugin/plugin.json	Patch version bump 0.23.0 → 0.23.1	None
plugins/planning/CHANGELOG.md	New [0.23.1] entry	None
plugins/planning/skills/plan/SKILL.md	Two prose rewrites (lines 35 and 119)	None

Checked specifically for:

• Injection surfaces (command, path, template, prompt): No new shell commands, no new variable interpolations, no adversarial text in the rewrites.
• Secret / credential handling: None present or touched.
• GitHub Actions patterns (pull_request_target, workflow_run, script injection via github context, permission widening): No workflow files in the diff.
• Supply-chain / dependency pins: No dependency or action pin changes.
• Authorization / access-control gaps: No config or permission changes.

The pre-existing !``...``` shell interpolations in SKILL.md (git branch, git log, git status`) are unmodified by this PR and carry no elevated risk.

[claude]

Claude finished @kyle-sexton's task in 1m 35s —— View job

---

PR Review

• Gather context — read changed files and diff
• Review SKILL.md changes for correctness and SSOT alignment
• Review plugin.json version bump
• Review CHANGELOG.md entry
• Post findings

---

This is a clean, focused doc-only fix. Three files changed, two targeted rewrites in plan/SKILL.md, plus the expected version bump and changelog.

SKILL.md — Line 35 (design-default axes walk)

Correctness: ✓
The new wording correctly shifts the framing from derivation to audit. The cross-skill alignment claim holds up:

• design/SKILL.md:178 owns configurability, extension points, observability, testability as "Design defaults."
• design-handoff/SKILL.md:39 already read: "/planning:plan next walks its design-default checklist against the plan`" — the two skills now agree.
• Magic-literal hygiene is correctly kept as plan's own check (it's a code-review concern, not a design-derivation concern), extracted into its own sentence.

The one minor observation: the replacement sentence is long and dense (roughly 3× the old sentence). It's all accurate, but a reader skimming quickly has more to parse. Not a blocking issue for a doc-only patch.

SKILL.md — Line 119 (build-technique selection)

Correctness: ✓
The distinction drawn is sound: design/viability unknowns route upstream; integration sequencing on the kept slice stays plan's own call. The "spike-first, then tracer-bullet the kept slice" logic from the old text is preserved ("When an upstream feasibility spike and ship-commitment both hold, sequence the kept tracer-bullet slice after the spike's outcome lands"). The nudge "not by habit" is correctly moved into the opening clause rather than standing alone — a small readability improvement.

The PR rationale (spike-vs-tracer-bullet is de-risking sequencing, not a design re-derivation) is well-reasoned and the text upholds it.

plugin.json — version bump

Correct: 0.23.0 → 0.23.1 (patch) is the right semver level for a documentation-only change with no behavior change.

CHANGELOG.md

Correct: Entry is under ## [0.23.1] → ### Changed, follows Keep a Changelog 1.1.0 format, summarizes both changed hunks accurately, and notes "Documentation-only; no behavior change (#265)."

Summary

No bugs, no security concerns, no SSOT violations introduced. The fix does exactly what it says: makes plan a thin consumer of design artifacts rather than a re-deriver. All cross-skill claims verified against the actual files. Approve when ready.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[claude]

Claude finished @kyle-sexton's task in 54s —— View job

---

Security Review

• Gather context
• Review PR diff
• Read changed files
• Assess security findings
• Post final review

---

No security issues found.

This PR is documentation-only — three files changed, all editorial:

File	Change	Security surface
plugins/planning/.claude-plugin/plugin.json	Patch version bump 0.23.0 → 0.23.1	None
plugins/planning/CHANGELOG.md	New [0.23.1] entry	None
plugins/planning/skills/plan/SKILL.md	Two prose rewrites (lines 35 and 119)	None

Checked specifically for:

• Injection surfaces (command, path, template, prompt): No new shell commands, no new variable interpolations, no adversarial text in the rewrites.
• Secret / credential handling: None present or touched.
• GitHub Actions patterns (pull_request_target, workflow_run, script injection via github context, permission widening): No workflow files in the diff.
• Supply-chain / dependency pins: No dependency or action pin changes.
• Authorization / access-control gaps: No config or permission changes.

The pre-existing !``...``` shell interpolations in SKILL.md(lines 11–13:git branch, git log, git status`) are unmodified by this PR and carry no elevated risk — they are read-only status commands.

[claude]

Claude finished @kyle-sexton's task in 1m 20s —— View job

---

PR Review

• Gather context
• Read changed files and diff
• Verify cross-skill alignment claims
• Review version bump and changelog
• Post findings

---

This is a clean, focused doc-only fix. Three files changed; two targeted prose rewrites in plan/SKILL.md; version bump and changelog entry are correct. I independently verified all cross-skill claims against the live files.

plan/SKILL.md — Line 35 (design-default axes walk)

Correctness: ✓

The ownership split is accurate:

• configurability / extension points / observability / testability → design/SKILL.md:178 confirms: "when discussion touches configurability, extension points, observability, or testability, open a design thread for it." plan auditing these rather than re-deriving them is correct.
• type-collaboration shape → design/SKILL.md covers type modeling (type inventory, domain modeling, topology phases) — attributing this to design's type modeling is correct.
• magic-literal hygiene kept as plan's own check — correct; this is a code-review/quality concern, not a design-derivation concern.
• Cross-skill alignment holds: design-handoff/SKILL.md:39 reads: "Extension / config / observability threads RESOLVED or TAGGED-DEFERRED — /planning:plan next walks its design-default checklist against the plan" — the two skills now agree.

One non-blocking note: the replacement sentence is roughly 3× longer and denser than the original single-list line. The content is accurate but takes more parsing for a reader skimming during a planning session. Not a blocker for a doc-only patch.

plan/SKILL.md — Line 119 (build-technique selection)

Correctness: ✓

The distinction drawn is sound and well-reasoned. The old text treated spike-vs-tracer-bullet as plan's own call across all uncertainty types (including design unknowns). The new text correctly partitions:

• design / viability unknown → routes upstream to /planning:design or a throwaway spike — plan consumes the outcome.
• kept-slice integration sequencing (tracer bullet / walking skeleton) → remains plan's own call.

The "spike-then-tracer-bullet when both a feasibility unknown and ship-commitment hold" logic is preserved: "When an upstream feasibility spike and ship-commitment both hold, sequence the kept tracer-bullet slice after the spike's outcome lands."

The following paragraph (Integration-first phase ordering, line 121) still coheres — it keys off "once the technique is the kept branch (tracer bullet / walking skeleton)" which aligns correctly with what the new line 119 establishes.

plugin.json — version bump

Correct: 0.23.0 → 0.23.1 (patch) is the right semver level for a documentation-only change.

CHANGELOG.md

Correct: Entry appears under ## [0.23.1] → ### Changed, follows Keep a Changelog 1.1.0 format, accurately summarizes both changed hunks, and notes "Documentation-only; no behavior change (#265)."

---

Summary: No bugs, no security concerns, no SSOT violations introduced. Cross-skill ownership claims verified directly from design/SKILL.md and design-handoff/SKILL.md. The fix correctly makes plan a thin consumer of design artifacts rather than a re-deriver, and all downstream coherence (integration-first ordering, the SSOT note at line 68) is preserved.