write-report

name	write-report
description	Synthesize experiment results into a structured research report for the research/ directory. Handles both conclusive and inconclusive outcomes. Use when invoked by the research recipe after experiments complete.

Write Report Skill

Synthesize scope findings, experiment design, and experiment results into a structured research report. The report is committed to the research/ directory in the worktree and becomes the primary deliverable of the research recipe.

This skill handles both conclusive and inconclusive outcomes — inconclusive results are valid findings, not failures.

When to Use

• As the reporting step of the research recipe (phase 2)
• After /run-experiment has produced results (or after retry exhaustion)

Arguments

/write-report {worktree_path} {results_path} [--inconclusive]

• {worktree_path} — Absolute path to the worktree (required). First path-like token after the skill name.
• {results_path} — Absolute path to the experiment results file (required). Second path-like token.
• --inconclusive — Optional flag indicating experiments were inconclusive (retry exhaustion or insufficient evidence). When present, the report emphasizes what was learned and why evidence was insufficient, rather than framing as a failure.

Critical Constraints

NEVER:

• Modify source code files outside the research/ directory
• Fabricate or embellish results — report exactly what was measured
• Omit the methodology section — reproducibility requires it
• Frame inconclusive results as failures — they are valid findings
• Create the report outside the worktree's research/ directory

ALWAYS:

• Use model: "sonnet" when spawning all subagents via the Task tool
• Write the report to research/ in the worktree root
• Include experiment scripts inline as fenced code blocks for reproducibility
• Commit the report to the worktree before returning
• Include a "What We Learned" section regardless of outcome
• Link back to the originating GitHub issue if an issue number is available

Workflow

Step 1 — Gather All Artifacts

Read all available artifacts from the worktree:

1. Experiment plan: .autoskillit/temp/experiment-plan.md
2. Scope report: .autoskillit/temp/scope/ (if available in worktree)
3. Experiment results: {results_path}
4. Any raw data files in .autoskillit/temp/run-experiment/
5. Standardized metrics: scan .autoskillit/temp/run-experiment/ for *_metrics.json files (e.g., accuracy_metrics.json, parity_metrics.json). If present, read them — they will populate the Standardized Metrics Assessment section of the report.
6. Experiment code: scan the worktree for scripts, fixtures, and tools added during implementation

Step 2 — Determine Report Type

Based on the --inconclusive flag and the experiment results status:

Conclusive (no --inconclusive flag):

• Full report with definitive findings
• Clear answer to the research question
• Recommendations based on evidence

Inconclusive (--inconclusive flag or status = INCONCLUSIVE/FAILED):

• Emphasize what was learned despite lack of definitive answer
• Document boundary conditions established
• Clearly state what additional work would produce a conclusive result
• Distinguish between "negative result" (evidence against hypothesis) and "inconclusive" (insufficient evidence either way)

Step 3 — Write Report

Create the report directory and file:

research/YYYY-MM-DD-{slug}/
  report.md       # The main research report
  scripts/        # Extracted experiment scripts (optional, if complex)

The {slug} is a kebab-case summary of the research topic (max 40 chars).

The report structure:

# {Research Title}

> Research report for [Issue #{N}]({issue_url}) — {date}

## Executive Summary

{2-3 paragraph overview: what was investigated, key methodology, headline
finding, and recommendation. Written last, placed first.}

## Background and Research Question

{Context: why this investigation was initiated, what decision it informs,
what was known before this experiment.}

## Methodology

### Experimental Design
{From the experiment design: hypothesis, variables, controls. Include
enough detail for independent reproduction.}

### Environment
- **Repository commit:** {output of `git rev-parse HEAD` — the exact commit this experiment ran against}
- **Branch:** {current branch name}
- **Package versions:** {output of the project's package manager — e.g., `cargo tree`, `pip freeze`, `conda list`, or the contents of lock files. Include ALL relevant dependency versions, not just top-level.}
- **Hardware/OS:** {if relevant to the experiment}
- **Custom environment:** {if a micromamba/conda environment.yml was used, note it and its location}

### Procedure
{Step-by-step description of what was executed.}

## Results

{Present data from the experiment. Use tables, code blocks, or whatever
format best represents the measurements. No interpretation in this
section — just facts.}

### Standardized Metrics

{Include this section when `*_metrics.json` files are present in
`.autoskillit/temp/run-experiment/`. Omit entirely if no metrics JSON was produced.}

| Metric | Dimension | Dataset | Value | Threshold | Status |
|--------|-----------|---------|-------|-----------|--------|
| {metric_name} | {Accuracy/Parity} | {dataset} | {value} | {threshold} | ✅ PASS / ❌ FAIL |

{If any metrics failed: note which solver level or dataset showed the failure
and whether it is within acceptable range for the experiment's scope.}

## Observations

{Notable patterns, anomalies, unexpected behaviors discovered during
the experiment.}

## Analysis

{Interpret the results. Compare against the hypothesis. Explain anomalies.
Connect findings to the original research question. Include statistical
analysis if relevant to the experiment type.}

## What We Learned

{Regardless of outcome, document:}
- {Key insight 1}
- {Key insight 2}
- {Boundary conditions established}
- {Methodology learnings for future experiments}

## Conclusions

{Direct answer to the research question.}

## Recommendations

{Actionable next steps based on findings — what to keep, revert, modify,
or investigate further. Include justification for each recommendation.}

## Appendix: Experiment Scripts

{Include key experiment scripts as fenced code blocks. These are preserved
for reproducibility even after the worktree is cleaned up.}

### {script_name.ext}
```{language}
{script content}

Appendix: Raw Data

{If raw data is small enough, include inline. Otherwise, reference the files committed alongside this report.}

### Step 4 — Commit and Emit

1. Create the research directory in the worktree:
   `mkdir -p research/YYYY-MM-DD-{slug}/`
2. Write `report.md` to that directory.
3. If experiment scripts are complex (>50 lines), also save them as separate
   files in `research/YYYY-MM-DD-{slug}/scripts/`.
4. Commit to the worktree:

git add research/ git commit -m "Add research report: {brief title}"

After committing, emit the structured output token as the very last line of
your text output:

> **IMPORTANT:** Emit the structured output tokens as **literal plain text with no
> markdown formatting on the token names**. Do not wrap token names in `**bold**`,
> `*italic*`, or any other markdown. The adjudicator performs a regex match on the
> exact token name — decorators cause match failure.

report_path = {absolute_path_to_report.md}