feat: add structured reflection process to correct-behavior skill

[nsheaps]

Summary

• Adds the 5-step reflection structure to Step 1 of the correct-behavior skill: what handler said was wrong, own understanding, root cause, correct path, correct solution
• Adds contribution priority order section (PLUGINS > SKILLS > RULES) to Step 5
• Fixes plugin path reference: ai/plugins → ai-mktpl/plugins

Context

The structured reflection process was previously duplicated in nsheaps/.ai-agent-jack PERSONA.md. Handler feedback (PR #60 comment) was that this structure should live in the skill, not the persona.

Test plan

• Verify correct-behavior skill still reads cleanly end to end
• Verify the reflection structure covers the same ground as was in PERSONA.md

Co-Authored-By: Jack Oat <jack-nsheaps[bot]@users.noreply.github.com>

[github-actions]

Plugin Version Status

Versions are auto-bumped in PRs. Manual bumps to higher versions are preserved.

Plugin	Base	Current	Action
agentic-behavior	0.1.1	0.1.2	Already bumped

[henry-nsheaps]

❌ Previous review issues remain unaddressed — step numbering gap, copy-paste artifact, and incomplete path fix still need fixing.

❌ Step numbering jumps from 1 → 3 (missing Step 2) after merging old steps — agents will be confused
⚠️ 6. Contributions to fix has stray "6." prefix copied from source PERSONA.md
⚠️ Path fix ai/plugins → ai-mktpl/plugins only applied in 1 of 3 occurrences — conflicting guidance
⚠️ marketplace.json manually edited (should be auto-generated by CD)
✅ Structured 5-point reflection is well-organized and a clear improvement over open-ended questions
✅ Contribution priority order (PLUGINS > SKILLS > RULES) aligns with repo philosophy
✅ Version bump 0.1.1 → 0.1.2 is appropriate for content changes
✅ PR description accurately describes changes with good motivation context

🖱️ Click to expand for full details

Review Context

This is a follow-up review. The previous review requested changes on 4 items. Since then, only a merge commit of main was pushed — no content fixes were made. All 4 issues remain. I've re-raised each as inline comments with links back to the original threads for continuity.

Structured Reflection (Step 1) — Good

The new 5-point reflection structure is a meaningful improvement. Consolidating the old Steps 1 ("Reflect on Recent Work") and 2 ("Understand the Correction") into a single step with concrete structure (handler's correction → own understanding → root cause → correct path → correct solution) gives agents a deterministic framework rather than open-ended questions. This change aligns with the PR's stated motivation from handler feedback in nsheaps/.ai-agent-jack#60.

Step Numbering Gap — Must Fix

After merging old Step 2 into Step 1, the remaining steps were not renumbered. The file reads: Step 1 (line 33), Step 3 (line 47), Step 4 (line 55), Step 5 (line 85), Step 6 (line 122), Step 7 (line 146). The command explicitly says "You MUST follow these steps in order" — a missing Step 2 is a correctness issue that will confuse agents. Steps 3–7 should become 2–6.

Copy-Paste Artifact ("6.") — Should Fix

Line 91 reads **6. Contributions to fix — apply in this priority order:**. The "6." is a leftover from the PERSONA.md source where this was step 6 in a different list. In this context (nested under item 1 of Step 5), the numbering is misleading. Should be **Contributions to fix — apply in this priority order:**.

Incomplete Path Fix — Must Fix

The PR fixes ~/src/nsheaps/ai/plugins/... → ~/src/nsheaps/ai-mktpl/plugins/... in the Step 5 table (line 102), but leaves the old ai/plugins path in two other locations:

• Line 24 (Supported Scopes table): `~/src/nsheaps/ai/plugins/...`
• Line 77 (Step 4 review section): `~/src/nsheaps/ai/plugins/*/commands/*.md`

This creates contradictory guidance within the same command file — a correctness issue.

marketplace.json — Convention Violation

Manual edits to marketplace.json go against the convention documented in ci-cd/conventions.md. CD auto-generates this file on merge to main. The edit is harmless (will be overwritten) but adds unnecessary diff noise. Consider reverting this file.

Quality Score Rationale (65%)

Two correctness issues (step numbering gap + conflicting paths) bring the score down significantly. These aren't cosmetic — they directly affect whether agents can follow the command correctly. The "6." artifact and marketplace.json edit are minor deductions. The core content changes (reflection structure, priority order) are good.

Simplicity Score Rationale (90%)

The consolidation of two steps into one and the structured numbered list are simpler than the original. The only complexity concern is the dual guidance format (priority list + table) in Step 5, which could be confusing, but that's a pre-existing pattern.

Recommended follow-ups (non-blocking):

• Consider also updating the remaining ~/src/nsheaps/ai/... references outside the plugins/ path (lines 25, 75–76, 103–104, 131–138) if the marketplace repo has been fully renamed — these currently reference .ai/rules/ and .claude/rules/ paths under the old ai repo name
• The Step 5 dual guidance format (priority list + table) covers overlapping ground — a future simplification could unify them

Notes:¹²

Footnotes

1. Workflow Run: https://github.com/nsheaps/ai-mktpl/actions/runs/24149825781/attempts/1 ↩

2. PR: #394 ↩

[henry-nsheaps]

❌ Step numbering gap still present. After merging old Steps 1+2 into the new Step 1, the remaining steps were not renumbered. The file currently reads: Step 1, Step 3, Step 4, Step 5, Step 6, Step 7 — Step 2 is missing.

Since the command states "You MUST follow these steps in order," a missing Step 2 will confuse agents that try to follow sequentially. Steps 3–7 need to be renumbered to 2–6.

This was flagged in the previous review and has not been addressed.

[henry-nsheaps]

⚠️ Copy-paste artifact from PERSONA.md. The 6. prefix is a leftover from the source document where this content was step 6 in a different numbered list. Here, it's nested under item 1 of Step 5, so the numbering is misleading.

Suggested change

	**6. Contributions to fix — apply in this priority order:**
	**Contributions to fix — apply in this priority order:**

This was flagged in the previous review and has not been addressed.

[henry-nsheaps]

⚠️ Incomplete path fix. The ai/plugins → ai-mktpl/plugins path correction was applied here (line 102), but two other occurrences of the stale path remain in this file:

1. Line 24 (Supported Scopes table): `~/src/nsheaps/ai/plugins/...`
2. Line 77 (Step 4 review section): `~/src/nsheaps/ai/plugins/*/commands/*.md`

These create conflicting guidance — an agent reading the Supported Scopes table gets the old path, while one reading Step 5 gets the new path. Both should be updated for consistency.

This was flagged in the previous review and has not been addressed.

[henry-nsheaps]

⚠️ Manual marketplace.json edit. Per repo conventions in ci-cd/conventions.md: "Never manually edit marketplace.json — it is auto-generated by the CD workflow on merge to main."

This won't break anything (CD will overwrite on merge), but it's unnecessary churn. Consider reverting this file and letting CD handle it.

This was flagged in the previous review and has not been addressed.