report

What this skill does

# Report

Guidelines for generating branch stories, creating pull requests, and assessing release readiness.

## Agent Compatibility

This skill works on any Agent-Skills-compatible agent. The two Claude-Code mechanisms used below are **enhancements, not requirements**:

- **Parallel fan-out** — where a step spawns `general-purpose` subagents to run parts concurrently (the carry-over judge, the overview/section-review/release-readiness workers, the PR and release-note writers), that is the Claude Code optimization. On other agents, perform those parts **sequentially** in the same session; the inputs and outputs are identical.
- **User interaction** — where a step uses `AskUserQuestion`, use the agent's native way of presenting a multiple-choice question (or ask in plain chat). The decision points are mandatory; only the prompt mechanism varies.

## Run Workflow

Context-aware report orchestration. Auto-detects whether the caller is in a drive or trip workflow and routes accordingly.

### Step 0: Workspace Guard

```bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/branching/scripts/check-workspace.sh
```

Parse the JSON output. If `clean` is `true`, proceed silently to Step 1.

If `clean` is `false`, display the `summary` to the user and ask via AskUserQuestion with selectable options:
- **"Ignore and proceed"** - Continue with the report workflow. The unrelated changes will remain in the workspace after the command completes.
- **"Stop"** - Halt the command so you can handle the changes first.

If the user selects "Stop", end the command immediately.

### Step 1: Detect Context

```bash
bash ${CLAUDE_PLUGIN_ROOT}/skills/branching/scripts/detect-context.sh
```

Parse the JSON output. Route to the appropriate workflow based on `context`.

### Step 2: Route by Context

#### Work Context (`context: "work"`)

Route by `mode` from detect-context output:

##### Drive Mode (`mode: "drive"`)

1. **Bump version** following CLAUDE.md Version Management section (patch increment). **Skip if a "Bump version" commit already exists in the current branch** (check with `bash ${CLAUDE_PLUGIN_ROOT}/skills/branching/scripts/check-version-bump.sh`; if `already_bumped` is `true`, skip this step).
2. **Run the Write Story orchestration** (`## Write Story → ### Orchestration`, Phases 0–6) directly in this command (main-agent) context. The command itself spawns the leaf `general-purpose` subagents — there is no intermediate story-writer subagent.
3. **Display story content**: Read the story file at `.workaholic/stories/<branch-name>.md` and output the entire Markdown content so the developer can review inline.
4. **Display PR URL** captured from Phase 5 (mandatory).

##### Trip Mode (`mode: "trip"`)

1. **Bump version** following CLAUDE.md Version Management section (patch increment). **Skip if a "Bump version" commit already exists in the current branch** (check with `bash ${CLAUDE_PLUGIN_ROOT}/skills/branching/scripts/check-version-bump.sh`; if `already_bumped` is `true`, skip this step).
2. **Run the Write Story orchestration** (`## Write Story → ### Orchestration`, Phases 0–6) directly in this command (main-agent) context. The command itself spawns the leaf `general-purpose` subagents — there is no intermediate story-writer subagent.
3. **Display story content**: Read the story file at `.workaholic/stories/<branch-name>.md` and output the entire Markdown content so the developer can review inline.
4. **Display PR URL** captured from Phase 5 (mandatory).

##### Hybrid Mode (`mode: "hybrid"`)

Both trip artifacts and drive-style tickets exist on this branch. Drive Mode and Trip Mode run the identical Write Story orchestration, so follow Drive Mode. The orchestration captures the full narrative including any trip origin.

#### Worktree Context (`context: "worktree"`)

Not on a work branch, but worktrees exist.

1. Run `bash ${CLAUDE_PLUGIN_ROOT}/skills/branching/scripts/list-worktrees.sh`
2. Filter to worktrees where `has_pr` is `false` (unreported work)
3. If no unreported worktrees found: inform the user "No unreported worktrees found." and stop.
4. If exactly one unreported worktree: ask the user "Found worktree '<name>'. Generate report?" using AskUserQuestion. If confirmed, use it.
5. If multiple unreported worktrees: list them and ask the user which one to report on using AskUserQuestion.
6. Once selected, all subsequent git operations must run from within the worktree directory.
7. Re-run context detection from within the worktree and follow the appropriate mode workflow.

#### Unknown Context (`context: "unknown"`)

Ask the user: "Could not determine development context from branch '<branch>'. Are you working on a drive or trip?" using AskUserQuestion with options "Drive" and "Trip". Route accordingly.

## Write Story

Generate a branch story that serves as the single source of truth for PR content.

### Orchestration

Generate the story file, then create the PR and release note. The `/report` command (main agent) runs this orchestration directly: it executes the bash/Read/Write steps inline and spawns each leaf worker as a `subagent_type: "general-purpose"` Task whose prompt preloads a `core` skill and runs one section. There is no intermediate subagent — the command does all fan-out, so the fan-out stays one level deep (a subagent cannot spawn further subagents).

#### Phase 0: Gather Context

Gather all context by running `bash ${CLAUDE_PLUGIN_ROOT}/skills/gather/scripts/git-context.sh`. Returns: branch, base_branch, repo_url, archived_tickets, git_log.

#### Phase 1: Judge Active Carry-Overs

Run before the parallel agent batch so the verdicts flow into section-reviewer's input. Skip silently if `.workaholic/concerns/` is empty or absent.

1. **Spawn a carry-over judge** as `subagent_type: "general-purpose"` (`model: "opus"`) in a single Task call. The prompt instructs it to preload `core:report`, follow the `### Judge Carry-Overs` section with the given branch name and base branch, and return `{verdicts: [...]}`.
2. **Apply verdicts**: Write the returned `verdicts` array to `/tmp/carryover-verdicts.json`, then run:

   ```bash
   cat /tmp/carryover-verdicts.json | bash ${CLAUDE_PLUGIN_ROOT}/skills/report/scripts/apply-carryover-verdicts.sh
   ```

   Files marked `resolved` have `status:` flipped to `resolved`, `resolved_by_pr` / `resolved_by_commit` recorded, and are then moved to `.workaholic/concerns/archive/`. Files marked `still_active` stay in `.workaholic/concerns/`.

#### Phase 2: Spawn Story Generation Workers

Spawn 3 `subagent_type: "general-purpose"` leaf subagents in parallel (single message with 3 Task calls). Each prompt names the skill to preload, the section to run, the inputs, and the expected return schema:

- **release-readiness** (`model: "opus"`): preload `core:report`, run `## Assess Release Readiness`, return the releasability JSON. Pass archived tickets list and branch name.
- **overview-writer** (`model: "haiku"`): preload `core:report`, run `### Overview Generation`, return the overview JSON. Pass branch name and base branch.
- **section-reviewer** (`model: "haiku"`): preload `core:review-sections`, run it, return the sections 4-7 JSON (Outcome, Historical Analysis, Concerns, Successful Development Patterns). Pass branch name, archived tickets list, and the carryover verdicts file path `/tmp/carryover-verdicts.json`. The section-reviewer prepends `still_active` verdicts to section 6.

Wait for all 3 to complete. Track which succeeded and which failed.

#### Phase 3: Write Story File

1. **Gather Source Data**: Read archived tickets using Glob pattern `.workaholic/tickets/archive/<branch-name>/*.md`. Extract frontmatter (`commit_hash`, `category`) and content (Overview, Final Report).
2. **Write Story**: Follow the Story Content Structure section below.
3. **Update Index**: Add entry to `.workaholic/stories/README.md`.

#### Phase 4: Commit and Push Story

1. **Stage story and resolved carry-overs**: `git add .workaholic/stories/ .workaholic/c