Bug Fix — Decompose open-research-pr into prepare + lens + compose Steps

[Trecek]

Summary

open-research-pr fails 100% because it invokes exp-lens-* sub-skills via the Skill tool inside a headless -p session. When the sub-skill completes and emits its output token, it issues end_turn; in headless mode that terminates the entire session — Steps 5-7 (results summary, PR body, PR creation) are never reached.

The fix is a recipe-level decomposition into three isolated sessions: prepare_research_pr (reads report + plan, selects lenses, writes context files — no sub-skill invocations), run_experiment_lenses (runs each selected exp-lens-{slug} in its own parallel run_skill call), and compose_research_pr (validates diagrams, composes the PR body, creates the PR — no sub-skill invocations). Two secondary bugs are also fixed: the stale experiment_plan path and the report.md → README.md rename that invalidates context.report_path before open_research_pr reads it. open-research-pr is retired once the new skills are validated.

Architecture Impact

Process Flow Diagram

%%{init: {'flowchart': {'nodeSpacing': 40, 'rankSpacing': 55, 'curve': 'basis'}}}%%
flowchart TB
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;

    START([START])
    ESCALATE([ESCALATE STOP])
    RESEARCH_COMPLETE([research_complete])

    push_branch["● push_branch<br/>━━━━━━━━━━<br/>git push -u origin HEAD<br/>on_success → prepare_research_pr"]

    subgraph S1 ["★ SESSION 1 — prepare_research_pr"]
        direction TB
        PrepareSkill["★ prepare-research-pr<br/>━━━━━━━━━━<br/>reads README.md + experiment_plan<br/>synthesizes recommendation<br/>selects 1-2 exp-lens lenses<br/>writes context file per lens<br/>writes PR prep file<br/>NO Skill tool invocations"]
        PrepCapture["● context captures<br/>━━━━━━━━━━<br/>prep_path<br/>selected_lenses<br/>lens_context_paths"]
    end

    subgraph S2 ["★ SESSION 2 — run_experiment_lenses (parallel per lens)"]
        direction LR
        LensRun["● exp-lens-{slug}<br/>━━━━━━━━━━<br/>reads context_path (per lens)<br/>reads experiment_plan<br/>creates diagram file<br/>emits diagram_path<br/>NO parent-skill dependency"]
        LensCapture["● capture_list accumulates<br/>━━━━━━━━━━<br/>all_diagram_paths<br/>(comma-separated)"]
    end

    subgraph S3 ["★ SESSION 3 — compose_research_pr"]
        direction TB
        ComposeSkill["★ compose-research-pr<br/>━━━━━━━━━━<br/>reads prep file<br/>validates diagrams<br/>(keyword check)<br/>composes PR body<br/>gh pr create<br/>NO Skill tool invocations"]
        PrCapture["context captures<br/>━━━━━━━━━━<br/>pr_url"]
    end

    guard_pr_url{"guard_pr_url<br/>━━━━━━━━━━<br/>pr_url non-empty?"}
    REVIEW["review_research_pr"]

    START --> push_branch
    push_branch -->|"on_success"| PrepareSkill
    push_branch -->|"on_failure"| ESCALATE
    PrepareSkill --> PrepCapture
    PrepCapture -->|"on_success"| LensRun
    PrepCapture -->|"on_failure"| ESCALATE
    LensRun --> LensCapture
    LensCapture -->|"on_success OR on_failure"| ComposeSkill
    ComposeSkill --> PrCapture
    PrCapture -->|"on_success"| guard_pr_url
    PrCapture -->|"on_failure"| ESCALATE
    guard_pr_url -->|"pr_url set"| REVIEW
    guard_pr_url -->|"pr_url empty"| RESEARCH_COMPLETE

    class START,ESCALATE,RESEARCH_COMPLETE terminal;
    class push_branch handler;
    class PrepareSkill,ComposeSkill newComponent;
    class PrepCapture,LensCapture output;
    class PrCapture output;
    class LensRun phase;
    class guard_pr_url stateNode;
    class REVIEW handler;

Loading

Color Legend:

Color	Category	Description
Dark Blue	Terminal	Start, escalate-stop, and research-complete terminals
Orange	Handler	Existing execution steps (push_branch, review)
Green	New Component	★ New skills introduced by this PR (prepare, compose)
Dark Teal	Output	Captured context variables flowing between sessions
Purple	Phase	● Modified exp-lens skills (run_experiment_lenses iteration)
Teal	State	Routing decision guard (guard_pr_url)

Operational Diagram

%%{init: {'flowchart': {'nodeSpacing': 50, 'rankSpacing': 60, 'curve': 'basis'}}}%%
flowchart TB
    classDef cli fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef newComponent fill:#2e7d32,stroke:#81c784,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;

    subgraph SkillRegistry ["● SKILL REGISTRY (skill_contracts.yaml + defaults.yaml)"]
        direction TB

        subgraph Tier3 ["Tier 3 — Automation/PR Lifecycle"]
            direction LR
            PrepSkill["★ prepare-research-pr<br/>━━━━━━━━━━<br/>Part 1/3 research-PR flow<br/>outputs: prep_path<br/>selected_lenses<br/>lens_context_paths"]
            ComposeSkill["★ compose-research-pr<br/>━━━━━━━━━━<br/>Part 3/3 research-PR flow<br/>outputs: pr_url<br/>write_behavior: always"]
            OpenPR["open-pr<br/>━━━━━━━━━━<br/>General PR creation<br/>(unchanged)"]
        end

        subgraph Tier2 ["● Tier 2 — Interactive/Cook+Headless"]
            direction LR
            ExpLens["● exp-lens-{slug} (18 skills)<br/>━━━━━━━━━━<br/>New optional inputs added:<br/>context_path<br/>experiment_plan_path<br/>output: diagram_path"]
        end
    end

    subgraph Recipe ["● research.yaml — PR Preparation Phase"]
        direction TB
        PushBranch["● push_branch<br/>━━━━━━━━━━<br/>git push origin HEAD<br/>routes to → prepare_research_pr"]
        PrepStep["● prepare_research_pr step<br/>━━━━━━━━━━<br/>run_skill: prepare-research-pr<br/>captures: prep_path<br/>selected_lenses<br/>lens_context_paths"]
        LensStep["★ run_experiment_lenses step<br/>━━━━━━━━━━<br/>run_skill: exp-lens-{slug}<br/>capture_list: all_diagram_paths<br/>on_failure → compose (partial OK)"]
        ComposeStep["★ compose_research_pr step<br/>━━━━━━━━━━<br/>run_skill: compose-research-pr<br/>captures: pr_url"]
    end

    subgraph Config ["● CONFIGURATION"]
        direction TB
        Defaults["● defaults.yaml<br/>━━━━━━━━━━<br/>prepare-research-pr → tier3<br/>compose-research-pr → tier3<br/>completion_marker: %%ORDER_UP%%"]
        Contracts["● skill_contracts.yaml<br/>━━━━━━━━━━<br/>New: prepare-research-pr contract<br/>New: compose-research-pr contract<br/>Updated: 18 exp-lens contracts<br/>Removed: open-research-pr contract"]
    end

    subgraph Monitoring ["OBSERVABILITY"]
        direction TB
        PrepLog["★ .autoskillit/temp/prepare-research-pr/<br/>━━━━━━━━━━<br/>pr_prep_{ts}.md<br/>exp_lens_context_{slug}_{ts}.md<br/>(READ-WRITE — compose consumes)"]
        ComposeLog["★ .autoskillit/temp/compose-research-pr/<br/>━━━━━━━━━━<br/>pr_body_{ts}.md<br/>(WRITE-ONLY — humans inspect)"]
        LensDiag["● .autoskillit/temp/exp-lens-{slug}/<br/>━━━━━━━━━━<br/>exp_diag_{slug}_{ts}.md<br/>(WRITE-ONLY — compose validates)"]
    end

    PrepSkill -->|"registered in"| Defaults
    ComposeSkill -->|"registered in"| Defaults
    PrepSkill -->|"contract in"| Contracts
    ComposeSkill -->|"contract in"| Contracts
    ExpLens -->|"contracts updated in"| Contracts

    PushBranch --> PrepStep
    PrepStep -->|"run_skill"| PrepSkill
    PrepStep --> LensStep
    LensStep -->|"run_skill (per selected lens)"| ExpLens
    LensStep --> ComposeStep
    ComposeStep -->|"run_skill"| ComposeSkill

    PrepSkill --> PrepLog
    ExpLens --> LensDiag
    ComposeSkill --> ComposeLog
    PrepLog -->|"read by"| ComposeSkill
    LensDiag -->|"validated by"| ComposeSkill

    class PrepSkill,ComposeSkill newComponent;
    class ExpLens,PushBranch,PrepStep,Defaults,Contracts phase;
    class LensStep,ComposeStep newComponent;
    class PrepLog,LensDiag,ComposeLog output;
    class OpenPR handler;

Loading

Color Legend:

Color	Category	Description
Green	New Component	★ New skills and recipe steps introduced by this PR
Purple	Modified	● Existing components with updated contracts, routing, or inputs
Orange	Handler	Unchanged existing components (open-pr)
Dark Teal	Output	Observability artifacts written to .autoskillit/temp/

Closes #652

Implementation Plan

Plan file: /home/talon/projects/autoskillit-runs/impl-20260407-101349-407505/.autoskillit/temp/make-plan/open_research_pr_decompose_plan_2026-04-07_101349.md

🤖 Generated with Claude Code via AutoSkillit

Token Usage Summary

Step	uncached	output	cache_read	cache_write	count	time
plan	1.3k	47.2k	1.3M	99.2k	1	15m 17s
verify	19	21.5k	784.4k	63.3k	1	6m 44s
implement	1.5k	44.5k	7.6M	109.6k	1	14m 36s
fix	87	50.6k	7.8M	130.0k	1	20m 19s
open_pr	34	19.9k	1.3M	70.5k	1	7m 32s
Total	3.0k	183.7k	18.8M	472.5k		1h 4m

[Trecek]

AutoSkillit PR Review — Verdict: changes_requested

4 blocking issues found. See inline comments.

[Trecek]

[warning] cohesion: Function name test_87_skills_in_skills_extended is stale — the docstring and assertion now assert 89 skills (not 87). Rename to test_89_skills_in_skills_extended.

[Trecek]

[warning] cohesion: Step 7 stores the written path as prep_file_path but the Output section and skill_contracts.yaml declare the output token as prep_path. Rename the internal variable to prep_path to match the output contract and keep it consistent with other skills (e.g., pr_url, report_path).