🐛 Address review feedback from PR #55

[TechNickAI]

Addresses valid feedback from Claude bot reviews on PR #55. Clarifies next-skill convention (LLM offers handoff, user confirms), adds stability: experimental to brainstorm-synthesis as a concrete example, and aligns stability wording across docs.

[claude]

Code Review — PR #57

This is a clean, focused documentation improvement that addresses real feedback from PR #55. The changes are well-scoped and the core clarification is important.

What's Working Well

next-skill clarification is the right call. Distinguishing "suggestion with user confirmation" from "auto-chain" is a meaningful UX safety boundary. The new wording across both CLAUDE.md files is unambiguous:

"The LLM surfaces this as a suggestion — the user confirms before the next skill runs. Never auto-invoke silently."

This aligns with the heart-centered AI philosophy in the project (presence before solutions, user agency). Good call.

stability: experimental on brainstorm-synthesis is well-chosen. It's one of the more complex multi-agent skills and benefits from that signal. Having a concrete in-repo example of the field makes the docs self-demonstrating.

Table alignment improvement is a nice polish win — the padded columns are easier to scan.

Version bump consistency — 1.1.0 → 1.1.1 updated in both the actual SKILL.md and the example block in .claude/CLAUDE.md. That discipline matters for documentation examples staying in sync.

---

Minor Observations

1. LLM-enforced convention is fragile by design — worth being explicit about that.

The docs note: "The Claude Code harness ignores them; the LLM reads and acts on them as part of the skill content."

The "user confirms before next skill runs" guarantee relies entirely on the LLM reading and honoring the convention — there's no harness enforcement. This is a known architectural choice, but since this PR is specifically clarifying what users can expect, it might be worth one sentence acknowledging that this is a convention (not a technical guarantee) so power users aren't surprised if an LLM model skips the confirmation step.

Something like: "This is a convention enforced by the LLM reading the skill, not by the harness — model behavior may vary." Optional, not blocking.

2. next-skill: ship on an experimental skill.

The annotated example shows brainstorm-synthesis (now marked experimental) chaining to ship. The juxtaposition of "experimental" and "ship (to production)" in the same example might give readers pause. Since this is an illustrative example and the chain is already documented in the repo's canonical chains list, it's fine — just something to keep in mind if the example ever gets simplified.

3. Trailing spaces in the aligned table (.claude/CLAUDE.md requires row) are harmless but if Prettier runs over this file, it might reformat it. Not a blocker.

---

Verdict

Approve. The next-skill semantic clarification is the substance of this PR and it's correct. The rest is polish. No functional changes, no regressions, consistent cross-file update. Ready to merge.

[claude]

PR #57 Review

This is a focused documentation tightening addressing valid feedback from the PR #55 review. Changes are scoped to three files and the intent is clear.

Substance

next-skill semantic clarification — the right fix.

The original wording ("invokes the next skill when its task is complete") implied automatic chaining. The replacement ("offers the handoff... the user confirms before the next skill runs. Never auto-invoke silently.") correctly establishes this as a user-gateable suggestion. This matters for the heart-centered AI philosophy in this project — user agency should be explicit.

The change is applied consistently across both doc locations (.claude/CLAUDE.md and plugins/core/skills/CLAUDE.md) with slightly different but semantically equivalent phrasing, which is appropriate given the two files have different audiences.

stability: experimental on brainstorm-synthesis is a concrete win.

Adding the field to an actual in-repo skill (not just the example block) makes the docs self-demonstrating. The version bump (1.1.0 → 1.1.1) is correctly reflected in both the live SKILL.md and the example snippet in .claude/CLAUDE.md — that kind of cross-file consistency discipline prevents docs from drifting.

Annotated chains footnote is a useful disambiguation.

"source skills only — downstream commands like verify-fix can't declare requires back, and terminal skills like ship are invokable standalone"

This answers the "why doesn't verify-fix have requires: systematic-debugging?" question before readers ask it. Good preemptive clarity.

Minor Observations

1. Convention vs. enforcement. The docs state the LLM "should never silently invoke the next skill without user awareness" but this is enforced by the LLM reading the skill content, not the harness. A one-liner acknowledging this is a convention rather than a technical guarantee would set accurate expectations for power users who might build tooling around it. Not blocking — just a future-docs thought.

2. next-skill: ship on an experimental skill. The example juxtaposes experimental maturity with ship as the downstream target. Fine in context (it's illustrative), but worth keeping in mind if the example is ever simplified.

Verdict

Approve. The next-skill clarification is the substance of this PR and it's correct. Consistent cross-file updates, clean diff, no regressions. Ready to merge.