feat(han-planning): add plan-a-change for architecture-driven code changes - #207
Merged
Conversation
…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
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
This was referenced Sep 9, 2026
Draft
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/plan-a-changetohan-planning: a skill that plans an architecture-driven change to code that already exists, producing a planplan-work-items,tdd, orrefactorcan build from directly.architectural-analysisandplan-a-featureso disambiguation works in both directions.Why
Issue #183 names a gap between two existing skills.
architectural-analysisassesses an area and produces findings, then stops.plan-a-featurespecifies 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-orchestratedstructural-analyst,behavioral-analyst, andsoftware-architectand 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 output folder resolves through the
config-ruleprecedence chain, sooutput-directoryfrom either.han/config.mdgoverns it.How to verify
npm run lintandnpm test(95 tests, all passing on this branch).han-planning/skills/plan-a-change/references/surface-delta-rule.md, the file the issue's central complaint maps to.plan-a-change,plan-a-feature, andarchitectural-analysis. All three stay under the 1024-character target (765, 783, 843).han-planning/docs/skills/plan-a-change.md, scent line in the plugin README, entry indocs/skills/README.md, chain entry indocs/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-changeuses the boundary record fromplanning-boundary-rulebut not its visual-material convention, which is stated in the rule's consumer note. Revert withgit revert.