Skip to content

try-works/role-model / .agents/skills/recursive-mode

recursive-mode

Unverified

Repository workflow orchestration skill for staged implementation, locked artifacts, late-phase receipts, and durable memory maintenance. Use when executing recursive-mode runs, resuming a run, locking a phase, or verifying locks.

FileKindSize
.agent/PLANS.mdmarkdown2.6 KB
.codex/AGENTS.mdmarkdown7.5 KB
.gitattributesother522 B
.gitignoreother553 B
.recursive/AGENTS.mdmarkdown3.3 KB
.recursive/DECISIONS.mdmarkdown1.1 KB
.recursive/README.mdmarkdown8.5 KB
.recursive/RECURSIVE.mdmarkdown107.5 KB
.recursive/STATE.mdmarkdown1.6 KB
.recursive/config/recursive-router.jsonconfig1.4 KB
.recursive/memory/MEMORY.mdmarkdown3.3 KB
.recursive/memory/archive/.gitkeepother1 B
.recursive/memory/domains/.gitkeepother1 B
.recursive/memory/episodes/.gitkeepother1 B
.recursive/memory/incidents/.gitkeepother1 B
.recursive/memory/patterns/.gitkeepother1 B
.recursive/memory/skills/SKILLS.mdmarkdown4.3 KB
.recursive/memory/skills/availability/.gitkeepother1 B
.recursive/memory/skills/issues/.gitkeepother1 B
.recursive/memory/skills/patterns/.gitkeepother1 B
.recursive/memory/skills/patterns/delegated-verification-and-refresh.mdmarkdown1.7 KB
.recursive/memory/skills/patterns/phase8-skill-memory-promotion.mdmarkdown1.4 KB
.recursive/memory/skills/usage/.gitkeepother1 B
.recursive/memory/skills/usage/skill-discovery-and-evaluation.mdmarkdown1.6 KB
.recursive/run/.gitkeepother1 B
AGENTS.mdmarkdown7.8 KB
LICENSEother11.1 KB
README.mdmarkdown17.8 KB
SKILL.mdskill md13.1 KB
agents/code-reviewer.mdmarkdown6.1 KB
agents/implementer.mdmarkdown6.3 KB
agents/openai.yamlconfig202 B
docs/templates/commands/check-reusable-repo-hygiene.mdmarkdown1.3 KB
docs/templates/commands/recursive-closeout.mdmarkdown2.8 KB
docs/templates/commands/recursive-init.mdmarkdown2.2 KB
docs/templates/commands/recursive-lock.mdmarkdown1.3 KB
docs/templates/commands/recursive-review-bundle.mdmarkdown3.6 KB
docs/templates/commands/recursive-status.mdmarkdown2.0 KB
docs/templates/commands/recursive-subagent-action.mdmarkdown4.2 KB
docs/templates/commands/test-recursive-mode-smoke.mdmarkdown3.4 KB
docs/templates/hooks/hooks.jsonconfig400 B
docs/templates/hooks/run-hook.cmdscript1.2 KB
docs/templates/hooks/session-start.ps1script3.6 KB
docs/templates/hooks/session-start.shscript3.5 KB
references/agents-block.mdmarkdown7.4 KB
references/artifact-template.mdmarkdown70.7 KB
references/benchmark-addon/recursive-benchmark/BENCHMARK-ADDON.mdmarkdown6.7 KB
references/benchmark-addon/recursive-benchmark/recursive-benchmark/BENCHMARK-ADDON.mdmarkdown6.7 KB
references/benchmark-addon/recursive-benchmark/recursive-benchmark/references/patterns.mdmarkdown4.9 KB
references/benchmark-addon/recursive-benchmark/references/patterns.mdmarkdown4.9 KB
references/benchmarks/README.mdmarkdown1.5 KB
references/benchmarks/local-first-planner/00-requirements.mdmarkdown3.3 KB
references/benchmarks/local-first-planner/README.mdmarkdown1.1 KB
references/benchmarks/local-first-planner/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/local-first-planner/prompt-recursive-on.mdmarkdown14.8 KB
references/benchmarks/local-first-planner/scoring-rubric.mdmarkdown1.3 KB
references/benchmarks/local-first-planner/starter/.gitignoreother30 B
references/benchmarks/local-first-planner/starter/README.mdmarkdown264 B
references/benchmarks/local-first-planner/starter/index.htmlother316 B
references/benchmarks/local-first-planner/starter/package.jsonmanifest628 B
references/benchmarks/local-first-planner/starter/src/App.test.tsxother334 B
references/benchmarks/local-first-planner/starter/src/App.tsxother971 B
references/benchmarks/local-first-planner/starter/src/main.tsxother238 B
references/benchmarks/local-first-planner/starter/src/styles.cssother976 B
references/benchmarks/local-first-planner/starter/src/test-setup.tsscript43 B
references/benchmarks/local-first-planner/starter/src/vite-env.d.tsscript38 B
references/benchmarks/local-first-planner/starter/tsconfig.app.jsonconfig552 B
references/benchmarks/local-first-planner/starter/tsconfig.jsonconfig89 B
references/benchmarks/local-first-planner/starter/vite.config.tsscript214 B
references/benchmarks/release-readiness-dashboard/00-requirements.mdmarkdown5.9 KB
references/benchmarks/release-readiness-dashboard/README.mdmarkdown1.2 KB
references/benchmarks/release-readiness-dashboard/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/release-readiness-dashboard/prompt-recursive-on.mdmarkdown14.8 KB
references/benchmarks/release-readiness-dashboard/scoring-rubric.mdmarkdown1.8 KB
references/benchmarks/release-readiness-dashboard/starter/.gitignoreother30 B
references/benchmarks/release-readiness-dashboard/starter/README.mdmarkdown272 B
references/benchmarks/release-readiness-dashboard/starter/index.htmlother324 B
references/benchmarks/release-readiness-dashboard/starter/package.jsonmanifest628 B
references/benchmarks/release-readiness-dashboard/starter/src/App.test.tsxother342 B
references/benchmarks/release-readiness-dashboard/starter/src/App.tsxother979 B
references/benchmarks/release-readiness-dashboard/starter/src/main.tsxother238 B
references/benchmarks/release-readiness-dashboard/starter/src/styles.cssother976 B
references/benchmarks/release-readiness-dashboard/starter/src/test-setup.tsscript43 B
references/benchmarks/release-readiness-dashboard/starter/src/vite-env.d.tsscript38 B
references/benchmarks/release-readiness-dashboard/starter/tsconfig.app.jsonconfig552 B
references/benchmarks/release-readiness-dashboard/starter/tsconfig.jsonconfig89 B
references/benchmarks/release-readiness-dashboard/starter/vite.config.tsscript214 B
references/benchmarks/scientific-calculator-rust/00-requirements.mdmarkdown4.1 KB
references/benchmarks/scientific-calculator-rust/README.mdmarkdown1.4 KB
references/benchmarks/scientific-calculator-rust/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/scientific-calculator-rust/prompt-recursive-on.mdmarkdown16.6 KB
references/benchmarks/scientific-calculator-rust/scoring-rubric.mdmarkdown1.5 KB
references/benchmarks/scientific-calculator-rust/starter/.gitignoreother14 B
references/benchmarks/scientific-calculator-rust/starter/Cargo.lockmanifest25.7 KB
references/benchmarks/scientific-calculator-rust/starter/Cargo.tomlmanifest226 B
references/benchmarks/team-capacity-board/00-requirements.mdmarkdown3.6 KB
references/benchmarks/team-capacity-board/README.mdmarkdown1.0 KB
references/benchmarks/team-capacity-board/prompt-recursive-off.mdmarkdown1.1 KB
references/benchmarks/team-capacity-board/prompt-recursive-on.mdmarkdown14.8 KB
references/benchmarks/team-capacity-board/scoring-rubric.mdmarkdown1.4 KB
references/benchmarks/team-capacity-board/starter/.gitignoreother30 B
references/benchmarks/team-capacity-board/starter/README.mdmarkdown264 B
references/benchmarks/team-capacity-board/starter/index.htmlother316 B
references/benchmarks/team-capacity-board/starter/package.jsonmanifest628 B
references/benchmarks/team-capacity-board/starter/src/App.test.tsxother334 B
references/benchmarks/team-capacity-board/starter/src/App.tsxother971 B
references/benchmarks/team-capacity-board/starter/src/main.tsxother238 B
references/benchmarks/team-capacity-board/starter/src/styles.cssother976 B
references/benchmarks/team-capacity-board/starter/src/test-setup.tsscript43 B
references/benchmarks/team-capacity-board/starter/src/vite-env.d.tsscript38 B
references/benchmarks/team-capacity-board/starter/tsconfig.app.jsonconfig552 B
references/benchmarks/team-capacity-board/starter/tsconfig.jsonconfig89 B
references/benchmarks/team-capacity-board/starter/vite.config.tsscript214 B
references/bootstrap/RECURSIVE.mdmarkdown109.9 KB
references/fixtures/tiny-tasks-smoke-recipe.mdmarkdown2.6 KB
references/local-first-web-app-checklist.mdmarkdown1.6 KB
references/plans-canonical.mdmarkdown10.8 KB
scripts/check-reusable-repo-hygiene.ps1script625 B
scripts/check-reusable-repo-hygiene.pyscript6.3 KB
scripts/install-recursive-mode.ps1script36.0 KB
scripts/install-recursive-mode.pyscript31.8 KB
scripts/install-recursive-mode.shscript363 B
scripts/lint-recursive-run.ps1script739 B
scripts/lint-recursive-run.pyscript127.4 KB
scripts/recursive-closeout.ps1script1015 B
scripts/recursive-closeout.pyscript24.0 KB
scripts/recursive-init.ps1script18.7 KB
scripts/recursive-init.pyscript12.6 KB
scripts/recursive-lock.ps1script677 B
scripts/recursive-lock.pyscript12.6 KB
scripts/recursive-review-bundle.ps1script2.9 KB
scripts/recursive-review-bundle.pyscript22.1 KB
scripts/recursive-router-cli-configure.ps1script86 B
scripts/recursive-router-cli-configure.pyscript230 B
scripts/recursive-router-cli-init.ps1script81 B
scripts/recursive-router-cli-init.pyscript225 B
scripts/recursive-router-cli-invoke.ps1script83 B
scripts/recursive-router-cli-invoke.pyscript227 B
scripts/recursive-router-cli-probe.ps1script82 B
scripts/recursive-router-cli-probe.pyscript226 B
scripts/recursive-router-cli-resolve.ps1script84 B
scripts/recursive-router-cli-resolve.pyscript228 B
scripts/recursive-router-cli-validate.ps1script85 B
scripts/recursive-router-cli-validate.pyscript229 B
scripts/recursive-router-configure.ps1script798 B
scripts/recursive-router-configure.pyscript2.8 KB
scripts/recursive-router-init.ps1script490 B
scripts/recursive-router-init.pyscript925 B
scripts/recursive-router-invoke.ps1script1.5 KB
scripts/recursive-router-invoke.pyscript4.4 KB
scripts/recursive-router-probe.ps1script735 B
scripts/recursive-router-probe.pyscript1.6 KB
scripts/recursive-router-resolve.ps1script803 B
scripts/recursive-router-resolve.pyscript1.6 KB
scripts/recursive-router-validate.ps1script494 B
scripts/recursive-router-validate.pyscript804 B
scripts/recursive-status.ps1script674 B
scripts/recursive-status.pyscript97.7 KB
scripts/recursive-subagent-action.ps1script5.8 KB
scripts/recursive-subagent-action.pyscript12.4 KB
scripts/recursive-training-extract.ps1script586 B
scripts/recursive-training-extract.pyscript1.0 KB
scripts/recursive-training-grpo.ps1script1.2 KB
scripts/recursive-training-grpo.pyscript47.2 KB
scripts/recursive-training-loader.ps1script2.3 KB
scripts/recursive-training-loader.pyscript20.1 KB
scripts/recursive-training-mcp.ps1script721 B
scripts/recursive-training-mcp.pyscript10.1 KB
scripts/recursive-training-phase8-trigger.ps1script1.4 KB
scripts/recursive-training-phase8-trigger.pyscript4.0 KB
scripts/recursive-training-sync.ps1script735 B
scripts/recursive-training-sync.pyscript6.9 KB
scripts/recursive_phase_rules.pyscript12.7 KB
scripts/recursive_router_cli_lib.pyscript77 B
scripts/recursive_router_lib.pyscript84.5 KB
scripts/run-recursive-benchmark.ps1script2.1 KB
scripts/run-recursive-benchmark.pyscript376.1 KB
scripts/test-recursive-mode-smoke.ps1script1.0 KB
scripts/test-recursive-mode-smoke.pyscript121.0 KB
scripts/test_install_recursive_mode.pyscript38.4 KB
scripts/test_lint_recursive_run.pyscript4.1 KB
scripts/test_recursive_phase_rules.pyscript21.4 KB
scripts/test_recursive_review_bundle.pyscript5.8 KB
scripts/test_recursive_router.pyscript53.3 KB
scripts/test_recursive_subagent_action.pyscript3.2 KB
scripts/test_recursive_training.pyscript12.0 KB
scripts/test_run_recursive_benchmark.pyscript160.0 KB
scripts/verify-locks.ps1script733 B
scripts/verify-locks.pyscript13.8 KB

scripts/recursive-training-loader.py

View on GitHub
#!/usr/bin/env python3
"""
Progressive memory loader for recursive-mode experiential knowledge.

Reads the memory router plus the repository memory plane, scores memory docs by
relevance to the current task, reads the most relevant docs, scores individual
items, and returns formatted context for the agent.

This script lives at `.recursive/scripts/recursive-training-loader.py` in the
target repository. It is copied there during recursive-mode installation.

This is the canonical way to load repo-specific experiential knowledge.
Run it directly when a task may benefit from repo-specific experiential memory.

Usage:
    # From repo root
    python .recursive/scripts/recursive-training-loader.py --repo-root . \
        --query "implementing frontend feature with react" \
        --files "apps/web/src/App.tsx,apps/web/src/stores/ui-store.ts"

    # Load all memories for a subsystem
    python .recursive/scripts/recursive-training-loader.py --repo-root . \
        --subsystem "web" --max-docs 5

    # Load specific task-type memories
    python .recursive/scripts/recursive-training-loader.py --repo-root . \
        --task-type "commit-workflow" --max-items 20

    # Dry run: show what would be loaded without returning content
    python .recursive/scripts/recursive-training-loader.py --repo-root . \
        --query "frontend rebuild" --dry-run

Progressive disclosure levels:
    Level 1: MEMORY.md (lightweight registry)
    Level 2: This loader + filesystem discovery (selective doc loading based on task context)
    Level 3: Agent applies specific items from loaded docs
"""

import argparse
import json
import re
import sys
from collections import defaultdict
from pathlib import Path
from typing import Dict, List, Optional, Tuple


# ---------------------------------------------------------------------------
# Memory doc discovery
# ---------------------------------------------------------------------------

class MemoryDoc:
    """Represents a single memory document (domain or training)."""

    def __init__(self, rel_path: str, doc_type: str, scope: str, item_count: int,
                 description: str = "", full_path: Optional[Path] = None):
        self.rel_path = rel_path
        self.doc_type = doc_type  # "domain" or "training"
        self.scope = scope
        self.item_count = item_count
        self.description = description
        self.full_path = full_path
        self._items: Optional[List[dict]] = None

    @property
    def items(self) -> List[dict]:
        """Lazy-load items from disk."""
        if self._items is None and self.full_path:
            self._items = self._parse_items()
        return self._items or []

    def _parse_items(self) -> List[dict]:
        """Parse ReasoningBank items from the markdown file."""
        if not self.full_path or not self.full_path.exists():
            return []
        content = self.full_path.read_text(encoding="utf-8")

        items = []
        # Match item blocks: ### RB-N: Title
        item_pattern = re.compile(
            r'### (RB-\d+):\s*(.+?)\n\n'
            r'\*\*Description:\*\*\s*(.+?)\n\n'
            r'\*\*Content:\*\*\s*(.+?)(?=\n\n```|\n### |\Z)',
            re.DOTALL
        )

        # Also parse schema metadata
        schema_pattern = re.compile(
            r'```yaml\n'
            r'rb_id: "(RB-\d+)"\n'
            r'title: "([^"]+)"\n'
            r'description: "([^"]+)"\n'
            r'task_type: "([^"]*)"\n'
            r'subsystem: "([^"]*)"\n'
            r'source_runs: (.+?)\n'
            r'applies_to: (.+?)\n'
            r'success_rate: ([\d.]+)\n'
            r'status: (\w+)\n'
            r'created_at: "([^"]+)"\n'
            r'```',
            re.DOTALL
        )

        # Build a map of schema metadata by rb_id
        schema_by_id: Dict[str, dict] = {}
        for m in schema_pattern.finditer(content):
            rb_id = m.group(1)
            schema_by_id[rb_id] = {
                "task_type": m.group(4),
                "subsystem": m.group(5),
                "success_rate": float(m.group(8)),
                "status": m.group(9),
                "source_runs": _parse_json_array(m.group(6)),
                "applies_to": _parse_json_array(m.group(7)),
            }

        for m in item_pattern.finditer(content):
            rb_id = m.group(1)
            item = {
                "rb_id": rb_id,
                "title": m.group(2).strip(),
                "description": m.group(3).strip(),
                "content": m.group(4).strip(),
            }
            # Merge schema metadata if available
            if rb_id in schema_by_id:
                item.update(schema_by_id[rb_id])
            else:
                item.update({
                    "task_type": "",
                    "subsystem": self.scope,
                    "success_rate": 0.0,
                    "status": "active",
                    "source_runs": [],
                    "applies_to": [],
                })

            if item.get("status") != "deprecated":
                items.append(item)

        return items


def _parse_json_array(text: str) -> List[str]:
    """Parse a JSON array string like ['a', 'b'] or ["a", "b"]."""
    text = text.strip()
    if not text or text == "[]":
        return []
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        # Fallback: parse comma-separated list
        items = re.findall(r'["\']([^"\']+)["\']', text)
        return items if items else []


# ---------------------------------------------------------------------------
# Registry discovery
# ---------------------------------------------------------------------------

class MemoryRegistry:
    """Discovers memory docs from the filesystem."""

    DOMAINS_DIR = ".recursive/memory/domains"
    TRAINING_DIR = ".recursive/memory/training"

    def __init__(self, repo_root: str):
        self.root = Path(repo_root).resolve()
        self.docs: List[MemoryDoc] = []

    def discover(self) -> List[MemoryDoc]:
        """Discover all memory docs from the filesystem."""
        self.docs = sorted(self._scan_filesystem().values(), key=lambda d: (d.doc_type, d.scope))
        return self.docs

    def _scan_filesystem(self) -> Dict[str, MemoryDoc]:
        """Scan .recursive/memory/ and exclude stale/deprecated docs by default."""
        docs: Dict[str, MemoryDoc] = {}

        for base_dir, doc_type in (
            (self.root / self.DOMAINS_DIR, "domain"),
            (self.root / self.TRAINING_DIR, "training"),
        ):
            if not base_dir.exists():
                continue
            for f in sorted(base_dir.glob("*.md")):
                content = f.read_text(encoding="utf-8")
                if "Status: STALE" in content or "Status: DEPRECATED" in content:
                    continue
                rel_path = str(f.relative_to(self.root / ".recursive/memory")).replace("\\", "/")
                if rel_path in docs:
                    continue  # Already discovered from registry
                item_count = len(re.findall(r'### RB-\d+:', content))
                docs[rel_path] = MemoryDoc(
                    rel_path=rel_path,
                    doc_type=doc_type,
                    scope=f.stem,
                    item_count=item_count,
                    full_path=f,
                )

        return docs

    def get_doc_by_scope(self, scope: str) -> Optional[MemoryDoc]:
        """Find a doc by its scope name (exact match)."""
        for doc in self.docs:
            if doc.scope.lower() == scope.lower():
                return doc
        return None


# ---------------------------------------------------------------------------
# Relevance scoring
# ---------------------------------------------------------------------------

class RelevanceScorer:
    """Scores memory docs and items by relevance to the current task."""

    def __init__(self, query: str, file_paths: List[str], subsystem: str = "",
                 task_type: str = ""):
        self.query = query.lower()
        self.query_parts = [p for p in re.split(r'[^a-zA-Z0-9]', self.query) if len(p) > 2]
        self.file_paths = [p.lower() for p in file_paths]
        self.subsystem = subsystem.lower()
        self.task_type = task_type.lower()

    def score_doc(self, doc: MemoryDoc) -> float:
        """Score a memory doc by relevance (0-100)."""
        score = 0.0
        scope_lower = doc.scope.lower()

        # Direct subsystem match (strong signal)
        if self.subsystem and self.subsystem in scope_lower:
            score += 30
        if self.subsystem and scope_lower in self.subsystem:
            score += 25

        # Direct task_type match for training docs
        if self.task_type and doc.doc_type == "training":
            if self.task_type in scope_lower:
                score += 25
            if scope_lower in self.task_type:
                score += 20

        # Query keyword overlap with scope
        for part in self.query_parts:
            if part in scope_lower:
                score += 8

        # File path overlap with doc scope (for domain docs)
        if doc.doc_type == "domain":
            for fp in self.file_paths:
                parts = fp.split("/")
                for part in parts:
                    if len(part) > 2 and part in scope_lower:
                        score += 10
                        break

        # Query keyword overlap with doc description
        desc_lower = doc.description.lower()
        for part in self.query_parts:
            if part in desc_lower:
                score += 5

        # Prefer docs with more items (more signal)
        score += min(doc.item_count * 0.5, 5)

        return score

    def score_item(self, item: dict) -> float:
        """Score an individual memory item by relevance (0-100)."""
        score = 0.0
        title = item.get("title", "").lower()
        desc = item.get("description", "").lower()
        content = item.get("content", "").lower()
        applies_to = [a.lower() for a in item.get("applies_to", [])]
        item_task = item.get("task_type", "").lower()
        item_subsystem = item.get("subsystem", "").lower()
        success_rate = item.get("success_rate", 0.0)

        all_text = f"{title} {desc} {content}"

        # Direct task_type match
        if self.task_type:
            if self.task_type in item_task:
                score += 20
            if item_task in self.task_type:
                score += 15

        # Direct subsystem match
        if self.subsystem:
            if self.subsystem in item_subsystem:
                score += 15
            if item_subsystem in self.subsystem:
                score += 10

        # Query keyword overlap
        for part in self.query_parts:
            if part in title:
                score += 10
            if part in desc:
                score += 5
            if part in content:
                score += 3

        # File path overlap with applies_to
        for fp in self.file_paths:
            fp_parts = fp.split("/")
            for fp_part in fp_parts:
                if len(fp_part) <= 2:
                    continue
                for tag in applies_to:
                    if fp_part in tag or tag in fp_part:
                        score += 8
                        break

        # Success rate bonus (prefer proven items)
        if isinstance(success_rate, float) and success_rate > 0.8:
            score += 3
        if isinstance(success_rate, float) and success_rate > 0.95:
            score += 2

        # Penalize very long content (less focused)
        if len(content) > 300:
            score -= 2

        return score


# ---------------------------------------------------------------------------
# Memory loader
# ---------------------------------------------------------------------------

class MemoryLoader:
    """Main loader: discovers docs, scores relevance, returns formatted context."""

    def __init__(self, repo_root: str):
        self.repo_root = Path(repo_root).resolve()
        self.registry = MemoryRegistry(repo_root)
        self.docs = self.registry.discover()

    def load(self, query: str = "", file_paths: List[str] = None,
             subsystem: str = "", task_type: str = "",
             max_docs: int = 3, max_items: int = 10,
             dry_run: bool = False) -> str:
        """Load the most relevant memory items for the given task context.

        Args:
            query: Description of the current task
            file_paths: Files being modified
            subsystem: Target subsystem (optional, stronger signal)
            task_type: Target task type (optional, stronger signal)
            max_docs: Max memory docs to read
            max_items: Max items to return
            dry_run: If True, only report what would be loaded

        Returns:
            Formatted memory context string ready to inject into agent prompt
        """
        file_paths = file_paths or []
        scorer = RelevanceScorer(query, file_paths, subsystem, task_type)

        # --- Level 2: Score and select docs ---
        scored_docs = []
        for doc in self.docs:
            score = scorer.score_doc(doc)
            if score > 0:
                scored_docs.append((score, doc))

        scored_docs.sort(key=lambda x: x[0], reverse=True)
        selected_docs = scored_docs[:max_docs]

        if dry_run:
            return self._format_dry_run(selected_docs, max_items)

        # --- Level 3: Read selected docs, score items ---
        all_items: List[Tuple[float, dict, str]] = []  # (score, item, doc_path)
        for doc_score, doc in selected_docs:
            for item in doc.items:
                item_score = scorer.score_item(item)
                # Blend doc relevance with item relevance
                blended = item_score + (doc_score * 0.3)
                all_items.append((blended, item, doc.rel_path))

        all_items.sort(key=lambda x: x[0], reverse=True)
        top_items = all_items[:max_items]

        return self._format_output(top_items, selected_docs, query)

    def _format_output(self, items: List[Tuple[float, dict, str]],
                       docs: List[Tuple[float, MemoryDoc]],
                       query: str) -> str:
        """Format the loaded items as context for the agent."""
        lines = [
            "=" * 60,
            "REPOSITORY EXPERIENTIAL KNOWLEDGE (Loaded via Memory Loader)",
            "=" * 60,
            "",
            f"Query: {query or '(none)'}" if query else "",
        ]

        if docs:
            lines.append("Sources loaded:")
            for score, doc in docs:
                lines.append(f"  - {doc.rel_path} ({doc.item_count} items, relevance: {score:.1f})")
            lines.append("")

        if not items:
            lines.append("No relevant experiences found for this task and file set.")
            lines.append("")
            lines.append("Tip: If you're starting a new task type, run training first:")
            lines.append("  python .recursive/scripts/recursive-training-grpo.py --repo-root .")
            return "\n".join(lines)

        lines.append(f"Top {len(items)} relevant learnings (ordered by relevance):\n")

        for idx, (score, item, doc_path) in enumerate(items, 1):
            rb_id = item["rb_id"]
            title = item["title"]
            desc = item["description"]
            content = item["content"]
            task_type = item.get("task_type", "")
            applies_to = item.get("applies_to", [])
            success = item.get("success_rate", 0.0)
            source_runs = item.get("source_runs", [])

            sr_str = f" [success: {success:.0%}]" if isinstance(success, float) and success > 0 else ""
            tt_str = f" [{task_type}]" if task_type else ""
            applies_str = ", ".join(applies_to) if applies_to else ""
            runs_str = f" (from: {', '.join(source_runs[:3])}{'...' if len(source_runs) > 3 else ''})" if source_runs else ""

            lines.append(f"{idx}. [{rb_id}{tt_str}]{sr_str} {title}")
            lines.append(f"   {desc}")
            lines.append(f"   {content}")
            if applies_str:
                lines.append(f"   Applies to: {applies_str}")
            if runs_str:
                lines.append(f"   Source runs{runs_str}")
            lines.append("")

        lines.append("-" * 60)
        lines.append("Apply these learnings when relevant. They are scoped to THIS repository.")
        lines.append("=" * 60)

        return "\n".join(lines)

    def _format_dry_run(self, docs: List[Tuple[float, MemoryDoc]], max_items: int) -> str:
        """Format dry-run output showing what would be loaded."""
        lines = [
            "=" * 60,
            "DRY RUN: Memory Loader Preview",
            "=" * 60,
            "",
        ]

        if not docs:
            lines.append("No memory docs match the current task context.")
            return "\n".join(lines)

        lines.append(f"Would load top {len(docs)} memory doc(s):")
        for score, doc in docs:
            lines.append(f"  - {doc.rel_path} ({doc.item_count} items, score: {score:.1f})")

        lines.append("")
        lines.append(f"Would return top {max_items} items across all selected docs.")
        lines.append("Run without --dry-run to load the actual content.")
        return "\n".join(lines)

    def load_all_flat(self) -> str:
        """Load ALL memory items as a flat list (for README/IDE files)."""
        items = []
        for doc in self.docs:
            for item in doc.items:
                items.append(item)

        if not items:
            return ""

        lines = ["## Repository Experiential Knowledge (ReasoningBank)\n"]
        lines.append("Lessons learned from prior recursive-mode runs in THIS repository:\n")
        for item in sorted(items, key=lambda x: x.get("rb_id", "")):
            rb_id = item["rb_id"]
            title = item["title"]
            desc = item["description"]
            content = item["content"]
            applies = ", ".join(item.get("applies_to", []))
            lines.append(f"- [{rb_id}] **{title}**: {desc} {content}")
            if applies:
                lines.append(f"  (applies to: {applies})")
        return "\n".join(lines)


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def main():
    parser = argparse.ArgumentParser(
        description="Progressive memory loader for recursive-mode experiential knowledge"
    )
    parser.add_argument("--repo-root", type=str, required=True,
                        help="Path to git repository root")
    parser.add_argument("--query", type=str, default="",
                        help="Description of the current task (e.g., 'implementing frontend feature')")
    parser.add_argument("--files", type=str, default="",
                        help="Comma-separated list of file paths being modified")
    parser.add_argument("--subsystem", type=str, default="",
                        help="Target subsystem (e.g., 'web', 'artifacts', 'api-worker')")
    parser.add_argument("--task-type", type=str, default="",
                        help="Target task type (e.g., 'commit-workflow', 'test-validation')")
    parser.add_argument("--max-docs", type=int, default=3,
                        help="Maximum memory docs to load (default: 3)")
    parser.add_argument("--max-items", type=int, default=10,
                        help="Maximum items to return (default: 10)")
    parser.add_argument("--dry-run", action="store_true",
                        help="Show what would be loaded without returning content")
    parser.add_argument("--all", action="store_true",
                        help="Load all items as flat list (for README generation)")
    args = parser.parse_args()

    loader = MemoryLoader(args.repo_root)

    if args.all:
        output = loader.load_all_flat()
        if output:
            print(output)
        else:
            print("No memory items found.")
        return

    file_paths = [f.strip() for f in args.files.split(",") if f.strip()] if args.files else []

    output = loader.load(
        query=args.query,
        file_paths=file_paths,
        subsystem=args.subsystem,
        task_type=args.task_type,
        max_docs=args.max_docs,
        max_items=args.max_items,
        dry_run=args.dry_run,
    )
    print(output)


if __name__ == "__main__":
    main()
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall