richfrem/learning-loop

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See ./requirements.txt for the dependency lockfile (currently empty — standard library only).

---

Learning Loop

The Learning Loop is a structured cognitive continuity protocol ensuring that knowledge survives across isolated agent sessions. It is designed to be universally applicable to any agent framework.

CRITICAL: Anti-Simulation Rules

YOU MUST ACTUALLY PERFORM THE STEPS LISTED BELOW. Describing what you "would do", summarizing expected output, or marking a step complete without actually doing the work is a PROTOCOL VIOLATION.

Closure is NOT optional. If the user says "end session" or you are wrapping up, you MUST run the full closure sequence. Skipping any step means the next agent starts blind.

---

The Iron Chain

Prerequisite: You must establish a valid session context upon Wakeup before modifying any code.

Orientation → Synthesis → Strategic Gate → Red Team Audit → [Execution] → Loop Complete (Return to Orchestrator)

---

Phase I: Orientation (The Scout)

Goal: Establish Identity & Context. Trigger: First action upon environment initialization.

1. Identity Check: Read any local orientation documents or primers provided by the user's environment.
2. Context Loading: Retrieve the historical session state (the "Context Snapshot" or equivalent state file) to understand what the previous agent accomplished.
3. Report Readiness: Output: "Orientation complete. Context loaded. Ready."

STOP: Do NOT proceed to work until you have completed Phase I.

---

Phase II: Intelligence Synthesis

1. Mode Selection: Decide if you are doing standard documentation (recording ADRs) or exploratory research.
2. Synthesis: Perform your research. Aggregate findings into clear, modular markdown files in the project's designated learning/ or memory/ directory.

Phase III: Strategic Gate (HITL)

Human-in-the-Loop Required

1. Review: Present architectural findings or strategic shifts to the User.
2. Gate: Wait for explicit "Approved" or "Proceed".
   • If FAIL: Backtrack to Phase VIII (Self-Correction).

Phase IV: Red Team Audit

1. Bundle Context: Compile your proposed plans into a single, cohesive research packet.
2. Action: Submit the packet to the User (or a designated Red Team adversarial sub-agent) for rigorous critique.
3. Gate: Do not proceed to execution until the Audit returns a "Ready" verdict.

Execution Branch (Post-Audit)

Choose your Execution Mode:

Option A: Standard Agent (Single Loop)

• Action: You write the code, run tests, and verify yourself.
• Trust But Verify & TDD Constraints: Do not bypass verification. You must write and execute comprehensive unit/integration tests (TDD). Perform a strict delta diff check on your own modifications to ensure no stubs or placeholders ("TODO", "TBD") are committed.

Option B: Dual Loop

• Action: Delegate execution to a scoped, isolated Inner Loop agent.
• CLI & Model Selection: Interactively ask the user which LLM CLI backend (agy, claude, copilot, etc.) and specific model to use for the sub-agent. Pass these settings to the runner command, appending < /dev/null to prevent SIGTTIN process halts.
• Command: Open the triple-loop-learning SKILL. Execute according to its instructions.
• Return: Once Inner Loop finishes, resume here at Phase V (Synthesis).

---

Session Close (MANDATORY — DO NOT SKIP ANY STEP)

This loop is now complete. You must formally exit the loop and return control to the Orchestrator. Skipping any close step means the next agent starts blind and the flywheel stalls.

Phase V: Completion & Handoff

The specific learning cycle is finished. You must now return control.

1. Verify Completion: Ensure the research or analysis goal you set out to achieve has been genuinely met.
2. Save Retrospective: Save any retrospective or survey findings to a local file (e.g., ./retrospective-[date].md) or stdout.
3. Hand off: Stop generating new actions and explicitly pass your findings back to the Orchestrator.
4. DO NOT:
   • Do not generate learning_package_snapshot.md (the primary agent's RLM Synthesizer does this).
   • Do not run context-bundler to seal the session (the primary agent does this).
   • Do not push traces to HuggingFace or update Vector DBs (the primary agent does this).
   • Do not commit to Git (the primary agent does this).
5. Memory promotion is the responsibility of the calling system (e.g., agent-agentic-os).
6. Terminate Loop: Explicitly state "Learning Loop Complete. Passing control to Orchestrator."

---

Phase Reference

| Phase | Name | Action Required | |-------|------|-----------------| | I | Orientation | Load context, last survey, last session log | | II | Synthesis | Create/modify research artifacts | | III | Strategic Gate | Obtain "Proceed" from User | | IV | Red Team Audit | Compile packet for adversary review | | V | Completion & Handoff | Verify completion, save retrospective locally, return control to Orchestrator |

---

Task Tracking Rules

You are not "done" until the active task tracker says you're done.

• Always use the user's preferred task tracking system (e.g., markdown kanbans, automated CLIs) to move tasks.
• NEVER mark a task done without running its verification sequence first.
• If using a markdown board, always display the updated board to the user to confirm the move registered.

---

Dual-Loop Integration

When a Learning Loop runs inside a Dual-Loop session:

| Phase | Dual-Loop Role | Notes | |-------|---------------|-------| | I (Orientation) | Outer Loop boots, orients | Reads boot files + spec context | | II-III (Synthesis/Gate) | Outer Loop plans, user approves | Strategy Packet generated | | IV (Audit) | Outer Loop snapshots before delegation | Pre-execution checkpoint | | (Execution) | Inner Loop performs tactical work | Code-only, isolated | | Verification | Outer Loop inspects Inner Loop output | Validates against criteria | | V (Handoff) | Outer Loop receives results | Triggers global retrospective |

Key rule: The Inner Loop does NOT run Learning Loop phases. All cognitive continuity is the Outer Loop's responsibility.

Cross-reference: dual-loop SKILL