Skip to content

Correct /han-update-documentation for five-plugin layout, and update all docs#47

Merged
mxriverlynn merged 2 commits into
mainfrom
fix/han-update-documentation-multi-plugin
Jun 2, 2026
Merged

Correct /han-update-documentation for five-plugin layout, and update all docs#47
mxriverlynn merged 2 commits into
mainfrom
fix/han-update-documentation-multi-plugin

Conversation

@mxriverlynn
Copy link
Copy Markdown
Collaborator

@mxriverlynn mxriverlynn commented Jun 2, 2026

Summary

This PR teaches the /han-update-documentation skill to audit the four-plugin layout instead of the old single-plugin/ layout, so that documentation sweeps actually find every skill and agent now that Han ships as multiple plugins.

  • The doc-update skill now discovers skills across four plugin roots (han.core, han.github, han.reporting, han.feedback) and agents from the one root that has them (han.core), replacing every hardcoded plugin/skills and plugin/agents path that no longer exists on disk.
  • Pre-requisite detection deepens its find to maxdepth 3 (the manifests now sit one level lower under named plugin folders) and probes each named skill root directly, so the skill no longer silently fails to locate its own inputs.
  • Four operator docs were corrected to match what the skills actually do today: an expanded dispatch list for structural-analyst, a third spec-aware artifact (feature-technical-notes.md) documented across iterative-plan-review and plan-implementation, and section-name fixes in update-pr-description.
  • Reviewer attention: the substance is whether the new find invocations and the {plugin} placeholder convention cover exactly the roots that exist, with no root missed and no dead plugin/ path left behind.

What to look at first

  • The new ### Plugin roots block in SKILL.md is the central decision: it establishes that {plugin} means one of the four skill roots and that agents live only under han.core. Every other path edit in the skill and its two reference files inherits this convention, so confirm the four roots named here match the repository layout (han.core, han.github, han.reporting, han.feedback).
  • The feature-technical-notes.md documentation thread spans three files (iterative-plan-review, plan-implementation, and indirectly the spec-aware flow). Check that the "absence is not a gap" framing is consistent everywhere: the file is created lazily and only when a load-bearing mechanic is captured, and each doc says so the same way.
  • The pre-requisite find change from maxdepth 2 to maxdepth 3 plus the switch to explicitly-named roots (find han.core han.github han.reporting han.feedback ...) is the failure-mode fix. Worth a glance to confirm a missing root degrades gracefully (the 2>/dev/null suppression) rather than aborting the whole sweep.

Files of interest

  • .claude/skills/han-update-documentation/SKILL.md — the central change: plugin-root discovery, the new ### Plugin roots block, and updated sweep find commands.
  • .claude/skills/han-update-documentation/references/audit-checklist.md — rewrites every skill/agent path rule to the {plugin} convention and han.core/agents.
  • .claude/skills/han-update-documentation/references/scope-mapping.md — updates the changed-path-to-entity mapping table and cascade rules to the four-root layout.
  • docs/skills/iterative-plan-review.md — documents the new feature-technical-notes.md spec-aware artifact and its lazy-creation semantics.
  • docs/agents/structural-analyst.md — expands the dispatch list to include /iterative-plan-review and /plan-implementation.

The skill predated the multi-plugin restructure and assumed a single
plugin/ directory (plugin/skills, plugin/agents, one plugin.json at
depth 2). Its prereq markers and Step 2 inventory targeted paths that
no longer exist, so the skill could not run.

Point the prereqs, sweep enumeration, source-of-truth reads, index
consistency check, scope-mapping, and audit-checklist at the real
layout: skills across han.core/han.github/han.reporting/han.feedback,
agents only in han.core/agents, manifests at {plugin}/.claude-plugin/.
- update-pr-description: rename stale 'Test Plan' to 'How this was
  tested' (the section the SKILL.md actually produces).
- iterative-plan-review: document the conditional third companion
  file artifacts/feature-technical-notes.md (spec-aware mode).
- plan-implementation: list artifacts/feature-technical-notes.md as a
  read/linked source-spec companion alongside decision-log/team-findings.
- structural-analyst: add /iterative-plan-review and /plan-implementation
  to its dispatcher list, matching sibling spine agents.
@mxriverlynn mxriverlynn marked this pull request as ready for review June 2, 2026 16:32
@mxriverlynn mxriverlynn merged commit 5f2c98d into main Jun 2, 2026
@mxriverlynn mxriverlynn deleted the fix/han-update-documentation-multi-plugin branch June 2, 2026 16:33
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