docs: add fix-issue skill with TDD protocol and symptom→layer table

[yscraft]

Summary

• Adds .claude/skills/fix-issue.md — a fast-path workflow for diagnosing and fixing bugs in mxcli, with a symptom → layer → file table so future fixes start at the right file rather than a broad codebase search
• Updates CLAUDE.md to reference the skill in the PR/commit review checklist

Test plan

• Read .claude/skills/fix-issue.md and verify the table and TDD protocol are accurate
• Verify CLAUDE.md checklist references the skill correctly

🤖 Generated with Claude Code

[github-actions]

AI Code Review

What Looks Good

• The new .claude/skills/fix-issue.md provides a clear, actionable workflow for diagnosing bugs in mxcli with a symptom→layer→file table and TDD protocol
• The update to CLAUDE.md properly integrates the skill into the PR/commit review checklist under a new "Bug fixes" section
• The example fix (Issue BUG: Some "list operations" in the microflow description are wrong #212) in the skill file demonstrates the workflow concretely with specific file changes and test additions
• The skill encourages test-first development and updating the symptom table after fixes, creating a self-improving knowledge base
• Documentation is concise and follows the project's existing skill file patterns

Minor Issues

• In the skill file's TDD protocol example, the test command references go test ./mdl/executor/... ./sdk/mpr/... but the actual test paths might vary (e.g., some formatter tests live in mdl/executor/cmd_<domain>_format_<area>_test.go). This is minor as the intent is clear
• The example fix mentions sdk/microflows/microflows_actions.go but the current codebase uses sdk/microflows/actions.go - however, this is presented as a historical example (Issue BUG: Some "list operations" in the microflow description are wrong #212) so it's acceptable as-is
• The symptom table's "Fix pattern" column could benefit from more consistent verb tense (e.g., "Add case" vs "Check the storage name"), but this doesn't hinder usability

Recommendation

Approve. The PR successfully adds a valuable diagnostic skill that improves bug-fixing efficiency without duplicating existing documentation or violating any MDL syntax rules (as it contains no MDL changes). The checklist update ensures the skill will be used in future PR reviews.

---

Automated review via OpenRouter (Nemotron Super 120B) — workflow source

[ako]

Review

Overall: useful concept, but the reference example holds up PR #217 as exemplary — and #217 has real bugs I just flagged. The core idea (maintain a symptom→layer→file lookup, grow it with every fix) is solid and self-maintaining. Two concrete issues before merge.

What I like

• Symptom → file table is a genuine accelerant. For recurring classes of bug (missing parser case, missing formatter case), the table cuts diagnosis from "grep the codebase" to "open this file." High ROI.
• Self-maintaining by design. The "add a row after every fix" rule prevents bitrot — future fixes grow the table, which is how this kind of doc should work.
• Small and reversible. Docs-only, zero code risk, CLAUDE.md hook is one checklist section.
• TDD emphasis is right for this repo. Parser/formatter layers are easy to cover with focused unit tests; pushing that as the default path matches how the surrounding tests are already structured.

Concerns

1. Hardcoded Windows-specific path in the committed file (line 45):

   Step 4: Run: /c/Users/Ylber.Sadiku/go/go/bin/go test ./mdl/executor/... ./sdk/mpr/...
   

   This is a personal path — won't exist in any other dev environment, and leaks a username. Replace with just go test ./mdl/executor/... ./sdk/mpr/.... Linters might not catch docs files but this will confuse every other reader.

2. The "Reference Fix" (PR fix: handle Microflows$Find, $Filter, $ListRange in list operation DESCRIBE #217) is the wrong seed example. I just reviewed fix: handle Microflows$Find, $Filter, $ListRange in list operation DESCRIBE #217 and flagged blockers: it emits $Page = RANGE($Orders, 0, 10); which isn't in the MDL grammar (DESCRIBE output won't round-trip); uses $currentObject/ prefix that doesn't match Studio Pro's convention; and silently degrades on malformed CustomRange. If this skill presents fix: handle Microflows$Find, $Filter, $ListRange in list operation DESCRIBE #217 as the model fix, it teaches future work to repeat those gaps. Either (a) wait for fix: handle Microflows$Find, $Filter, $ListRange in list operation DESCRIBE #217 to land cleanly before citing it, (b) cite a different PR as the seed, or (c) add "what this fix got wrong and why" alongside the success story so readers learn from both.

3. Minor accuracy nit: the table references formatActionStatement() — the actual function is formatAction() (see cmd_microflows_format_action.go). Verify each function name in the table matches what's in the code; a symptom table that points at a nonexistent function is worse than no table.

4. "Always write failing test first" is too absolute. Some fixes are one-character typos where the test-first dance adds friction without value. Suggest softening to: "Write a regression test that reproduces the bug — before the fix if practical, alongside the fix at minimum." Same outcome (regression coverage), doesn't force ceremony on trivial cases.

5. The "How to Use" flow implicitly assumes the symptom is already in the table. For novel bugs (most of them, early on), the skill doesn't help diagnosis — it just tells you to add a row afterward. Add a step 0: "If no row matches, diagnose normally; then seed the table with what you learned."

Minor

• Two rows duplicate content already in CLAUDE.md (CE0066 association semantics; CE0463 widget templates). Not a problem — duplication is fine if the table is the "first reference" — but worth linking back to CLAUDE.md rather than restating, so the canonical explanation stays in one place.
• Consider adding a row for the 03-page-examples.mdl / colActions class of bug (column-name sugar vs custom-content columns) — recent, concrete, and not obvious from the filename alone.

Verdict

Approve after (1) Windows path fixed and (2) the seed example is replaced or annotated. (3)–(5) are suggestions; none block.