Skip to content

feat(han-planning): add plan-a-change for architecture-driven code changes - #207

Merged
mxriverlynn merged 2 commits into
v5.5.0-betafrom
gh-183-plan-a-change
Sep 9, 2026
Merged

feat(han-planning): add plan-a-change for architecture-driven code changes#207
mxriverlynn merged 2 commits into
v5.5.0-betafrom
gh-183-plan-a-change

Conversation

@mxriverlynn

Copy link
Copy Markdown
Collaborator

Summary

  • Adds /plan-a-change to han-planning: a skill that plans an architecture-driven change to code that already exists, producing a plan plan-work-items, tdd, or refactor can build from directly.
  • Review the surface delta rule and the behavior-preservation gate closely. Those two carry the design.
  • No version bumps and no CHANGELOG entry. Adds reciprocal boundary clauses to architectural-analysis and plan-a-feature so disambiguation works in both directions.

Why

Issue #183 names a gap between two existing skills. architectural-analysis assesses an area and produces findings, then stops. plan-a-feature specifies behavior a user observes, and its content rule keeps symbol names out on purpose. Neither answers "these responsibilities are wrong, plan the fix", so the author of that issue hand-orchestrated structural-analyst, behavioral-analyst, and software-architect and synthesised the result themselves.

The issue makes three asks. This PR answers all three in one skill:

Code-level names are the subject, not a leak. The plan names types, modules, and methods, because it plans a structure an engineer works in rather than behavior a user observes. The altitude limit is different in kind: carry names, responsibilities, and contracts; never inline file bodies or prescribe line-level edits.

The surface delta is a target-state record, not a migration table. Five verbs, and every entry states what is true after the change in its own right, written so it would still be correct if every other entry were deleted. A removal always says where the responsibility went, or that it went away and why. This is the fix for the issue's "one removal had no target-state statement anywhere". A migration table is written from the call site inward, so a responsibility moving between two internal collaborators produces no row at all and vanishes from a document built that way.

Behavior preservation is a gate, not an assumption. Every delta entry is classified preserving, changing, or unknown. The last two are escalated before commit. An entry that cannot be classified is escalated rather than assumed safe.

Closes #183.

What it does

Twelve steps: establish the reason, record the scope boundary, establish the current state, select the team, propose the target state, settle the delta, run the behavior gate, review, sweep for YAGNI and scope, write, readability, present.

Two behaviors worth a reviewer's attention:

  • The reason is recorded and not assumed. Step 1 classifies why a change is being planned across six reason classes. A reported defect is one of them; a prior findings report is another. Neither is presumed to exist. A run with no recorded reason stops, because there is nothing for the YAGNI evidence test to test against.
  • Discovery is conditional. With a prior report, Step 2 reads it. Without one, Step 2 dispatches structural and behavioral analysts (plus concurrency on signal). That is the orchestration the issue describes doing by hand.

The output folder resolves through the config-rule precedence chain, so output-directory from either .han/config.md governs it.

How to verify

  • npm run lint and npm test (95 tests, all passing on this branch).
  • Read han-planning/skills/plan-a-change/references/surface-delta-rule.md, the file the issue's central complaint maps to.
  • Check the boundary clauses in three descriptions read correctly against each other: plan-a-change, plan-a-feature, and architectural-analysis. All three stay under the 1024-character target (765, 783, 843).
  • Confirm the docs coverage rule holds: long-form doc at han-planning/docs/skills/plan-a-change.md, scent line in the plugin README, entry in docs/skills/README.md, chain entry in docs/workflows.md.

Risk / rollback

Low. The change is additive: one new skill plus registration across the docs surfaces. The only edits to existing behavior are two description clauses and four consumer-list lines in the shared planning rules, none of which change what an existing skill does. plan-a-change uses the boundary record from planning-boundary-rule but not its visual-material convention, which is stated in the rule's consumer note. Revert with git revert.

…anges

Closes the gap issue #183 names between architectural-analysis, which
produces findings and stops, and plan-a-feature, which specifies behavior
a user observes and keeps symbol names out. Neither answers "these
responsibilities are wrong, plan the fix".

The skill takes whatever context is supplied, establishes the current
state, settles a target state, and produces a change plan that is
buildable directly by plan-work-items, tdd, or refactor.

Three properties answer the issue's three complaints:

- Code-level names are the subject rather than a leak. The plan names
  types, modules, and methods, because it plans a structure an engineer
  works in.
- The surface delta is a target-state record, not a migration table.
  Every element removed, added, moved, renamed, or re-scoped carries a
  statement that would still be correct if every other entry were
  deleted, so a removal always says where the responsibility went.
- Behavior preservation is a gate, not an assumption. Every delta entry
  is classified preserving, changing, or unknown, and the last two are
  escalated before they are committed.

The run reads a prior findings report when one exists and dispatches its
own structural, behavioral, and concurrency round when one does not. The
output folder resolves through the config-rule precedence chain.

Also adds reciprocal boundary clauses to architectural-analysis and
plan-a-feature, registers the skill across the docs surfaces, and adds it
to the four shared planning rules' consumer lists.
@mxriverlynn
mxriverlynn marked this pull request as ready for review September 9, 2026 15:47
The branch added the plan-a-change skill and the han-ddd plugin but left
several cross-plugin documentation surfaces pointing only one way.

- Add /plan-a-change to the sizing-aware skill list, the per-skill table,
  and the per-skill Sizing links in docs/sizing.md.
- Add /plan-a-change to the sizing, YAGNI, evidence, readability, and
  han-planning enumerations in docs/concepts.md, and add the missing
  /automated-test-planning to the sizing list there.
- Add the missing Sizing section to the plan-a-change and ddd-analysis
  long-form docs, recording that ddd-analysis sizes analysis depth rather
  than team size and defaults to medium.
- Add reverse boundary and Related documentation pointers to
  plan-a-change from architectural-analysis, plan-a-feature,
  plan-work-items, and refactor, including refactor's frontmatter.
- Name /plan-a-change as a dispatcher in the fourteen agent long-form docs
  it dispatches.
- Document the discriminating-power criterion in the test-engineer and
  edge-case-explorer Key concepts, matching their definitions.
- Fix two wrong-depth docs/ links in the automated-test-planning doc.
- Correct han-planning's plugin.json description, which claimed a
  han-core-only dependency while declaring han-communication too.

Claude-Session: https://claude.ai/code/session_01UGo7ozwZcFKu2yVHtrGMMm
@mxriverlynn
mxriverlynn merged commit d71e4f3 into v5.5.0-beta Sep 9, 2026
2 checks passed
@mxriverlynn
mxriverlynn deleted the gh-183-plan-a-change branch September 9, 2026 17:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant