reflexion — Claude Code skill: self-correcting code loop

---
name: reflexion
description: "Use for self-correcting implementation. Implements the reflexion loop: implement, validate, self-critique, retry (max 3 iterations)."
metadata:
  instruction_budget: "52"
  framework_dependency: "mycelium"
  framework_dependency_note: "This skill is designed to run within the Mycelium framework (https://github.com/haabe/mycelium). Standalone use will skip the canvas state, theory gates, and harness behavior the skill assumes. Install: /plugin install mycelium@haabe-mycelium."
---

# Reflexion Skill

Self-correcting implementation loop from the n-trax pattern.

## Workflow

### Iteration Loop (max 3)

**Step 1: Implement**
- Create the deliverable according to the specification/acceptance criteria.
  - Software: write code. Content: write/produce content. AI tool: write prompts/configs. Service: document workflow.
- Follow ${CLAUDE_PLUGIN_ROOT}/harness/engineering-principles.md (principles apply to all product types).
- Apply patterns from patterns.md.
- Check corrections.md for relevant past mistakes.

**Step 2: Validate**
- Software: Run tests, linter, type checker, security scan, accessibility checks (if UI).
  - **Security validation (OWASP)**: Check input validation, output encoding, parameterized queries, no hardcoded secrets, authentication/authorization patterns, dependency vulnerabilities. Reference OWASP Top 10:2025 categories for each check.
- Content: Review against learning objectives/editorial standards, check accessibility (captions, alt text), fact-check claims.
- AI tool: Run eval test cases, red-team testing, bias assessment.
- Service: Walk through the service blueprint end-to-end, verify documentation completeness.
- All: Verify acceptance criteria.

**Step 3: Self-Critique**
Review the implementation against (select items relevant to product_type):
- [ ] Engineering principles: DRY, KISS, YAGNI, SoC (apply to all product types)
- [ ] Security: Input validation, output encoding, no secrets, parameterized queries (software, ai_tool)
- [ ] Accessibility: Semantic HTML, keyboard nav, contrast, screen reader (software); captions, transcripts, alt text (content)
- [ ] Edge cases: What happens with unexpected input? Empty? Adversarial? (software, ai_tool)
- [ ] Error handling / user recovery: Are errors handled gracefully? Can users recover? (software, service)
- [ ] Quality: Factual accuracy, style consistency, source attribution (content); eval scores, safety scores (ai_tool)
- [ ] Naming / clarity: Do names reveal intent? Would a new reader understand this? (all)
- [ ] Completeness: Is anything missing that the user would expect? (all)

**Step 4: Decide**
- If all validations pass AND self-critique finds no issues: **DONE**
- If issues found AND iteration < 3: **FIX and return to Step 1**
- If iteration = 3 AND issues remain: **ESCALATE** with documented issues

### Escalation Protocol
When max iterations reached without full resolution:
1. Document what was attempted in each iteration.
2. Document remaining issues with severity assessment.
3. Recommend: fix now (blocking) vs. fix later (non-blocking) vs. accept risk.
4. Update corrections.md with learnings.

## Verification Modes

The validate step in the reflexion loop should use the appropriate verification mode:

### Rules-Based (deterministic)
- Linters, formatters, schema validators, type checkers
- Pass/fail is unambiguous — no judgment needed
- Always run first — fastest and cheapest
- Examples: `eslint`, `mypy`, `yamllint`, YAML schema validation against ${CLAUDE_PLUGIN_ROOT}/engine/canvas-guidance.yml

### Computational (deterministic)
- Test runners, build systems, security scanners
- Requires executing code — slower than rules-based
- Results are objective but may need interpretation (flaky tests)
- Examples: `pytest`, `npm test`, `cargo clippy`, OWASP dependency check

### Inferential (probabilistic)
- LLM-as-judge, peer review, heuristic evaluation
- Used when rules-based and computational verification are insufficient
- Results require confidence scoring — never treat as definitive
- Examples: `/mycelium:devils-advocate`, `/mycelium:usability-check`, auto-dogfood evaluation, design review
- The auto-dogfood system is an inferential verification loop

**Order**: Always attempt rules-based → computational → inferential. Only escalate to the next mode when the previous mode cannot verify the property in question.

*Source: Trivedy (Anatomy of an Agent Harness, LangChain blog). Three-mode taxonomy adapted from Böckeler (Harness Engineering, martinfowler.com — computational vs inferential distinction). Note: harnesses continue to matter even as models improve — they engineer systems around model intelligence, not just patch deficiencies.*

## Rules
- Each iteration must show measurable improvement over the previous.
- If the same issue recurs across iterations, investigate root cause rather than patching symptoms.
- Never skip the self-critique step, even if tests pass.
- Log the reflexion loop outcome in delivery-journal.md.
- **NUDGE-AT-FAILURE** (4-layer JIT composition): if the failure being reflexed on is a class a standard tool (linter, SAST, secrets scanner, dep audit) would have caught automatically, append a single-line nudge to the reflexion output: *"This class of failure is what `{tool}` catches automatically — want help wiring it up now?"* Never auto-install. Per `feedback-jit-nudge-not-push` (founder principle, 2026-05-26).

## Theory Citations
- Reflexion pattern (Shinn et al.)
- Clean Code (Martin)
- OWASP secure coding
- WCAG 2.1 AA