leap

# LEAP · Skill Builder LEAP does not choose the request type or interact with the user. SkillAlchemy selects the branch and handles each user checkpoint. LEAP runs the selected pipeline and returns the result. ## Branch Routing | Command | Branch | Pipeline | |---------|--------|----------| | `distill` / `distillation` | **Branch A** | Distillation pipeline — extract the target OS from raw data and compile it into a persona/tool skill | | `fuse` / `fusion` | **Branch B** | Fusion pipeline — method.skill (skeleton) × subject.skill(s) (flesh) → output.skill | ## Invocation Modes | Mode | Trigger | Behavior | |------|---------|----------| | **Full run** | No special keyword | Run the full pipeline and output a skill package | | **Plan only** | `stop after Stage 3` or `stop_after_stage: 3` | Run Branch A Stages 1-3 only; stop after writing `research_plan.json` | | **Resume** | `continue from Stage 4` or `resume_from_stage: 4` | Skip Branch A Stages 1-3; use the existing `research_plan.json` and run Stages 4-7 plus Gate 1 | --- # Branch A: Distillation Pipeline ```text Source Intake → Intake Assessment → Research Plan Design → Research Swarm → Gate 1: Merge → Exemplar Discovery → Synthesis (3 agents) → Skill Compilation ``` Core principle: extract the operating system behind the source, not just the content or answer. --- ## A-Stage 1: Source Intake Input: person, author, method, organization, domain, URL, repo, or local files. Create package workspace at `output/<target-slug>-skill/`: ``` output/<target-slug>-skill/ ├── README.md ├── SKILL.md.draft ├── references/ # agent reports + exemplars ├── intermediate/ # structured data └── examples/ # persona: required; tool: optional ``` > Do not pre-create `templates/`; output templates live in LEAP's shared layer and > are not needed in the generated skill. Write `intermediate/open_world_task.json` with the capability brief `g`, target, source-access specification `S` (allowed source types, retrieval channels, and exclusions), execution/package constraints `C`, and `depth_level`. Every later retrieval must comply with `S`; existing skills are not eligible exemplars unless `S` explicitly permits them. | `depth_level` | Effect | Use case | |:--|:--|:--| | `quick` | Agent count ≤3 | Rapid prototype | | `standard` | No correction to auto-assessment | Daily use (default) | | `deep` | Agent count upper bound +1, capped at 8 | Broader evidence coverage | --- ## A-Stage 2: Intake Assessment ### Step 1: Source Modality Analysis Classify every source by what it can reveal: | Modality | Examples | Reveals | |----------|---------|---------| | `transcript_interview` | podcasts, video captions, Q&A | spontaneous reasoning, analogies, changed positions | | `longform_text` | books, papers, essays, newsletters | core arguments, methodology, narrative structure | | `secondary_criticism` | reviews, biographies, analysis | external perspective, blind spots, competing views | | `video_subtitle` | YouTube, Bilibili captions | speech patterns, unscripted reasoning | | `social_media` | posts, threads | expression patterns, real-time reactions | | `code_repo` | git repos, PRs | architecture patterns, API contracts, testing strategy | For each modality present, note what operations it could reveal. Skip absent ones. ### Step 2: Domain Inference Read `domains/<domain>/domain.md` to confirm. Record primary + secondary domains. ### Step 3: Evidence Depth Assessment **Don't count sources — assess their density.** - ≥3 high-density sources across ≥2 modalities → **rich** (5-8 agents) - 1-2 high-density sources → **moderate** (3-5 agents) - 0 high-density, all medium/low → **sparse** (2-3 agents) Apply `depth_level` correction: quick→floor+cap at 3, standard→no change, deep→ceiling+1, cap at 8. ### Step 4: Skill Mode Determination | Target type | Skill mode | Behavior | |-------------|-----------|----------| | Person / author / expert | `persona` | First-person role-play. Includes Role-Playing Rules, Identity, How I Speak, and Decision Heuristics | | Domain / method / organization | `tool` | Third-person analytical. Has Activation Rules, Agentic Protocol, Operation Models | --- ## A-Stage 3: Research Plan Design ### How to select candidate operational factors 1. Start from Lens's candidate operational factors and acquisition targets. Hidden dimensions, brief-specific values, and matched contrastive tests are one planning mechanism, not separate discovery stages. 2. Read primary domain pack: `domains/<primary-domain>/domain.md` → candidate factors 3. **If persona, also read `domains/persona-os/domain.md`.** This cross-cutting layer provides OS extraction lenses (decision under constraint, failure processing, value conflict resolution, attention allocation, etc.). 4. Cross factors with source modality: match → active, no match → skip 5. Apply evidence depth cap: sparse→merge, moderate→1:1, rich→split 6. Derive a new candidate factor only when the source exposes a behavior-relevant distinction not already represented. For each active factor `d`, retain or construct a paired acquisition target `<d, x, x'>` whose contexts differ along `d`. Convert it into a focused research question asking whether the contexts require different treatment in condition, action, recovery, or verification. A factor is confirmed as an implicit requirement only when acquired evidence supports such a treatment difference. ### Self-Check Before Writing research_plan.json 1. **Depth match** — Does agent_count fall within the depth range? 2. **Modality coverage** — Are source_modalities_used actually present? 3. **Factor coverage** — Does every active factor have a matched acquisition target? 4. **Merge intent** — Deliberate or lazy? Document the rationale. ### Search direction must target dilemmas ``` Good: "What was the hardest decision at [event]? What options did they have?" Bad: "What is their leadership style?" ``` Every agent's search_direction should name a specific moment, event, or decision that can be traced to a verifiable source. Write `intermediate/research_plan.json` with one record per planned research agent. Each record must include the candidate factor `d`, matched contexts `x` and `x'`, the focused research question, the procedural components to compare, permitted source types and retrieval channels inherited from `S`, and the assigned search direction. Together these focused questions form `Q`. ### Plan-Only Mode Stop Point **If invoked with `stop after Stage 3` or `stop_after_stage: 3`:** Stop immediately after writing `research_plan.json`. Output: ``` Research plan generated and saved to intermediate/research_plan.json. [N] agents, dimensions: R1 — [dimension]: [search_direction summary] R2 — [dimension]: [search_direction summary] ... ``` Do not enter Stage 4. Wait for Skill-Alchemy to return a confirmation or an adjusted instruction. --- ## A-Stage 4: Research Swarm **Resume mode:** If invoked with `continue from Stage 4`, read the agent configuration directly from the existing `intermediate/research_plan.json`. Skip Stages 1-3. Launch N agents in parallel. Each agent writes `references/R<NN>-<agent_id>.md`: ``` Status: pass (or warning / fail) ## Structured Findings - Finding ID: stable identifier used by later artifacts - Acquisition Target: `<factor, x, x'>` - Context x: seed operating conditions - Treatment in x: source-grounded behavior, not an executable instruction - Evidence for x: source_id, type, confidence, and source-stated boundary - Context x': matched conditions with only the target factor changed - Treatment in x': source-grounded behavior, not an executable instruction - Evidence for x': source_id, type, confidence, and source-stated boundary - Affected Components: condition / action / recovery / verification - Relation: changed / invariant / unresolved ## Dilemma Decision Cases (≥2 required) ### Case N: [one-line summary] - Dilemma: specific conflict or hard choice - Constraints: what limited their options - Decision Steps: what they did, step by step - Outcome: what happened - Extractable Operation: generalizable rule/pattern/heuristic ## Evidence Sources (source_id, type, confidence) ## Supported Candidate Operations ## Rejected or Weak Candidate Operations ## Target-specific Patterns ## Boundaries and Uncertainties ## Recommendations for Later Skill Compilation ``` **Agent Contract:** Every report begins with `Status: pass` / `warning` / `fail`. Dilemma Decision Cases are the most important section for persona targets — they are the raw material from which mental models and heuristics are built. **Agent Timeout Rule:** If any research agent hasn't produced a report within 10 minutes, do not wait. Proceed with completed agents. Gate 1 checks: - Persona: ≥4 total Dilemma Cases across all completed reports → pass. <4 → downgrade depth to quick and relaunch with fewer (≤2) agents. - Tool: ≥2 total Dilemma Cases → pass. <2 → same downgrade. - Mark missing agents in `merge_report.json`: `"agents_lost": ["R2", "R3"]`. --- ## A-Gate 1: Research Merge Agent uses `data-analysis` skill to process reports: 1. Read all R1-Rn reports 2. Extract Status + all sections 3. **Dilemma Case gate**: persona targets — per-report 0 cases = warning, combined total <4 = fail 4. Normalize every paired finding into `evidence_matrix.json`, retaining both contexts, both treatments, affected components, boundaries, and evidence IDs. 5. Write one entry per acquisition target to `contrast_records.json`: - `changed`: evidence supports different treatment in at least one component; a source-stated applicability boundary along the target factor is sufficient evidence that the bounded component changes across the matched contexts; - `invariant`: evidence supports the same treatment across non-equivalent contexts; - `unresolved`: either side lacks enough evidence or the comparison conflicts. Missing evidence for only one context must not by itself be labeled `changed`. Use this schema: ```json { "factor": "d", "context_x": "seed context", "context_x_prime": "matched context with d changed", "component_relations": { "condition": "changed", "action": "invariant", "recovery": "unresolved", "verification": "invariant" }, "evidence_x": ["F01"], "evidence_x_prime": ["F02"], "overall_relation": "changed", "confirmed_implicit_requirement": true, "evidence_stated_boundary": "..." } ``` 6. Confirm a factor as an implicit requirement only when its contrast record is `changed`. Keep `invariant` and `unresolved` records for later scope decisions. 7. Detect cross-report contradictions and write `contradiction_report.json` and `merge-summary.md`. 8. Write `merge_report.json`, `evidence_matrix.json`, and `contrast_records.json`. Gate 1 merges and checks research evidence only. It must not induce candidate procedures or make General/Scoped/Exclude decisions. --- ## A-Stage 5: Exemplar Discovery Retrieve the best exemplars in real time from the public skill pool on skills.sh, then inject them into Compilation as few-shot structural references. ### Retrieval Workflow This stage runs only when existing skills are an allowed source type under `S`. Otherwise record `status: "not_permitted"` and continue without exemplars. 1. **Search with find-skills:** Call the skills.sh find-skills interface with keywords for the target. Return the top 20 candidate `skill_key` values. 2. **Download candidate SKILL.md files concurrently and score them mechanically:** - Download the SKILL.md files for all 20 candidates concurrently from GitHub raw. - Run `python3 scripts/score_skill.py --skill <path> --json` for each candidate. - Sort by `quality_score`: prioritize elite candidates (≥11) and discard drafts (<9). 3. **Select and inject the best candidates automatically:** - Take the top 3-5 elite exemplars, prioritizing scores ≥11. - Write them to `references/exemplars/exemplar-<N>.md`. - Write the scoring results to `references/exemplar_candidates.json` for audit. 4. **Handle cases with no qualified result:** - If every candidate scores below 9, broaden the search terms and search once more. - If no elite candidate is found after two rounds, set `status: "degraded"` in `exemplar_discovery.json`. - **You must still attempt to obtain at least one exemplar.** It is the basis for compilation quality. --- ## A-Stage 6: Synthesis Run the following steps in order. Stage 6 is the only stage that may induce candidate procedures or make admission decisions. ### S1: Decision Alignment Group findings by the procedural decision they inform, not by source topic. Write `operation_candidates.json`. Each candidate must have this shape: ```json { "candidate_id": "P01", "decision": "the procedural decision being made", "condition": {"content": "...", "evidence_ids": ["F01"]}, "action": {"content": "...", "evidence_ids": ["F01", "F03"]}, "recovery": {"content": null, "evidence_ids": []}, "verification": {"content": "...", "evidence_ids": ["F04"]} } ``` Leave an unsupported component empty. Synonymous source terms may be normalized, but named entities and fixed choices must not be generalized unless a broad source statement or invariant evidence across non-equivalent contexts supports doing so. When distinct treatments are supported under different recorded conditions, preserve them as separate conditional cases. Do not collapse them into one rule. Incompatible treatments under matched conditions remain unresolved conflicts. ### S2: Procedure Admission For each candidate, write an entry to `admission_records.json`: ```json { "candidate_id": "P01", "F_plus": ["F01", "F03", "F04"], "F_minus": [], "sigma": "widest operating scope supported by the listed evidence", "supported": true, "consistent": true, "reusable": true, "reuse_basis": "broad_source_statement | cross_context_invariance | none", "decision": "General", "rationale": "short evidence-based explanation" } ``` Apply these rules exactly: 1. `supported=true` only when every populated component is backed by evidence that applies within `sigma`. 2. `consistent=true` only when no `F_minus` evidence prescribes incompatible treatment under overlapping conditions within `sigma`. 3. Restrict `sigma` before classification when support holds only in a narrower scope. 4. `reusable=true` only when an allowed source explicitly states broader applicability or invariant evidence supports the same treatment across at least two non-equivalent contexts. A single source-local case is not reusable. 5. Classify as `General` when supported, consistent, and reusable; `Scoped` when supported and consistent but not reusable; otherwise `Exclude`. Write `admitted_general.json`, `admitted_scoped.json`, and `excluded_candidates.json` from these records. Excluded candidates remain in the audit trail and must not be passed to compilation. ### S3: Package Design Write `package_plan.json`. Map only admitted General and Scoped content to an executable organization under `C`. Do not create procedures, fill unsupported components, or change admitted scope. --- ## A-Stage 7: Skill Compilation Compile final package from all research + synthesis reports + exemplars.