Reflection Worker
NOTE: Startup and cleanup are handled by worker-base. This skill defines the WORK PROCEDURE.
When to Use This Skill
Features involving:
- Reflection score tracker calibration and normalization
- Hook registration in settings.json
- Token reporting pipeline fixes
- TokenAccountant persistence
- Evolution trigger behavior
- RECE reflection loop verification
Work Procedure
Read the feature description and CTO Directive #2 from AGENTS.md.
For score tracker work: Before ANY changes to reflection-score-tracker.cjs:
- Read
.claude/agents/core/reflection-agent.md to determine the ACTUAL scoring rubric
- Note the scale (0-1 vs 1-10) the prompt asks for
- Read existing score entries in reflection-log.jsonl to see what the LLM actually outputs
- Design normalization that handles BOTH scales defensively
Write tests first (red):
- Create test cases for 0-1 scale input
- Create test cases for 1-10 scale input
- Create test cases for mixed-scale input
- Create test cases for edge cases (0, 1, 10, NaN, undefined)
- Confirm all fail
Implement the fix (green):
- Add normalization logic:
if (score <= 1.0) normalizedScore = score * 10
- Update LOW_SCORE_THRESHOLD to match the rubric's Critical Fail boundary
- Ensure protected agents are excluded
- Ensure cooldown is respected
For hook registration: When registering hooks in settings.json:
- Read the existing hook format carefully
- Match the exact structure (event, command, matcher patterns)
- Verify the hook file exists and is parseable
- Test that the hook fires on the correct event
For token reporting: When fixing post-pipeline-token-report.cjs:
- Add structural detection (remaining tasks count, explicit metadata flag)
- Keep keyword detection as FALLBACK only
- Add unit test for non-keyword pipeline completion
- Add unit test for false-positive prevention
For TokenAccountant persistence:
- Use atomic writes (write-to-temp + rename)
- Handle corrupted file gracefully (try-catch, empty init)
- Handle missing file gracefully (create on first write)
- Add load() method that reads from disk
Run all reflection-related tests:
node --test tests/hooks/reflection-*.test.cjs
node --test tests/lib/reflection-score-tracker.test.cjs
Run broader suites for regression check:
pnpm test:framework
Commit with descriptive message.
Example Handoff
{
"salientSummary": "Fixed reflection-score-tracker.cjs: added defensive normalization (scores <= 1.0 multiplied by 10), calibrated LOW_SCORE_THRESHOLD to 4.0 (matching Critical Fail < 0.4 rubric = 4.0 on 1-10 scale). Registered force-step0-execution.cjs and reflection-data-aggregator.cjs in settings.json. Fixed token report to use structural pipelineComplete detection. Added disk persistence to TokenAccountant with atomic writes.",
"whatWasImplemented": "Score normalization in reflection-score-tracker.cjs handles 0-1 and 1-10 scales. Two hooks registered. Token report uses metadata.pipelineComplete as primary signal. TokenAccountant persists to .claude/context/metrics/token-usage.json with write-to-temp+rename.",
"whatWasLeftUndone": "",
"verification": {
"commandsRun": [
{
"command": "node --test tests/lib/reflection-score-tracker.test.cjs",
"exitCode": 0,
"observation": "All tests pass including both scale normalization"
},
{ "command": "pnpm test:framework", "exitCode": 0, "observation": "0 failures" }
],
"interactiveChecks": []
},
"tests": {
"added": [
{
"file": "tests/lib/reflection-score-tracker.test.cjs",
"cases": [
{ "name": "normalizes 0-1 scores to 1-10", "verifies": "CTO directive #2" },
{ "name": "passes through 1-10 scores unchanged", "verifies": "1-10 scale handling" },
{ "name": "handles mixed scale entries", "verifies": "defensive normalization" }
]
}
],
"coverage": "Score tracker, token report, and accountant persistence all covered"
},
"discoveredIssues": []
}
When to Return to Orchestrator
- Reflection-agent's rubric is ambiguous about scoring scale
- settings.json structure is unclear for hook registration
- Token reporting requires changes to the task creation pipeline (outside scope)
1---2name: reflection-worker3description: Fixes reflection system, evolution triggers, token reporting, and hook registration4metadata:5 source: https://skillmd.com/skills/oimiragieo/reflection-worker6---78# Reflection Worker910NOTE: Startup and cleanup are handled by `worker-base`. This skill defines the WORK PROCEDURE.1112## When to Use This Skill1314Features involving:1516- Reflection score tracker calibration and normalization17- Hook registration in settings.json18- Token reporting pipeline fixes19- TokenAccountant persistence20- Evolution trigger behavior21- RECE reflection loop verification2223## Work Procedure24251. **Read the feature description and CTO Directive #2 from AGENTS.md.**26272. **For score tracker work:** Before ANY changes to `reflection-score-tracker.cjs`:28 - Read `.claude/agents/core/reflection-agent.md` to determine the ACTUAL scoring rubric29 - Note the scale (0-1 vs 1-10) the prompt asks for30 - Read existing score entries in reflection-log.jsonl to see what the LLM actually outputs31 - Design normalization that handles BOTH scales defensively32333. **Write tests first (red):**34 - Create test cases for 0-1 scale input35 - Create test cases for 1-10 scale input36 - Create test cases for mixed-scale input37 - Create test cases for edge cases (0, 1, 10, NaN, undefined)38 - Confirm all fail39404. **Implement the fix (green):**41 - Add normalization logic: `if (score <= 1.0) normalizedScore = score * 10`42 - Update LOW_SCORE_THRESHOLD to match the rubric's Critical Fail boundary43 - Ensure protected agents are excluded44 - Ensure cooldown is respected45465. **For hook registration:** When registering hooks in settings.json:47 - Read the existing hook format carefully48 - Match the exact structure (event, command, matcher patterns)49 - Verify the hook file exists and is parseable50 - Test that the hook fires on the correct event51526. **For token reporting:** When fixing post-pipeline-token-report.cjs:53 - Add structural detection (remaining tasks count, explicit metadata flag)54 - Keep keyword detection as FALLBACK only55 - Add unit test for non-keyword pipeline completion56 - Add unit test for false-positive prevention57587. **For TokenAccountant persistence:**59 - Use atomic writes (write-to-temp + rename)60 - Handle corrupted file gracefully (try-catch, empty init)61 - Handle missing file gracefully (create on first write)62 - Add load() method that reads from disk63648. **Run all reflection-related tests:**6566 ```67 node --test tests/hooks/reflection-*.test.cjs68 node --test tests/lib/reflection-score-tracker.test.cjs69 ```70719. **Run broader suites** for regression check:7273 ```74 pnpm test:framework75 ```767710. **Commit** with descriptive message.7879## Example Handoff8081```json82{83 "salientSummary": "Fixed reflection-score-tracker.cjs: added defensive normalization (scores <= 1.0 multiplied by 10), calibrated LOW_SCORE_THRESHOLD to 4.0 (matching Critical Fail < 0.4 rubric = 4.0 on 1-10 scale). Registered force-step0-execution.cjs and reflection-data-aggregator.cjs in settings.json. Fixed token report to use structural pipelineComplete detection. Added disk persistence to TokenAccountant with atomic writes.",84 "whatWasImplemented": "Score normalization in reflection-score-tracker.cjs handles 0-1 and 1-10 scales. Two hooks registered. Token report uses metadata.pipelineComplete as primary signal. TokenAccountant persists to .claude/context/metrics/token-usage.json with write-to-temp+rename.",85 "whatWasLeftUndone": "",86 "verification": {87 "commandsRun": [88 {89 "command": "node --test tests/lib/reflection-score-tracker.test.cjs",90 "exitCode": 0,91 "observation": "All tests pass including both scale normalization"92 },93 { "command": "pnpm test:framework", "exitCode": 0, "observation": "0 failures" }94 ],95 "interactiveChecks": []96 },97 "tests": {98 "added": [99 {100 "file": "tests/lib/reflection-score-tracker.test.cjs",101 "cases": [102 { "name": "normalizes 0-1 scores to 1-10", "verifies": "CTO directive #2" },103 { "name": "passes through 1-10 scores unchanged", "verifies": "1-10 scale handling" },104 { "name": "handles mixed scale entries", "verifies": "defensive normalization" }105 ]106 }107 ],108 "coverage": "Score tracker, token report, and accountant persistence all covered"109 },110 "discoveredIssues": []111}112```113114## When to Return to Orchestrator115116- Reflection-agent's rubric is ambiguous about scoring scale117- settings.json structure is unclear for hook registration118- Token reporting requires changes to the task creation pipeline (outside scope)