qmu/report

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 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 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 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 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 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 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 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:

   cat /tmp/carryover-verdicts.json | bash 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 report, run ## Assess Release Readiness, return the releasability JSON. Pass archived tickets list and branch name.
• overview-writer (model: "haiku"): preload report, run ### Overview Generation, return the overview JSON. Pass branch name and base branch.
• section-reviewer (model: "haiku"): preload 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/concerns/
2. Commit: git commit -m "Add branch story for <branch-name>" (the same commit captures any carry-over archive moves from Phase 1, keeping audit history coherent)
3. Push branch: git push -u origin <branch-name>

Phase 5: Create PR and Generate Release Note

Spawn sequentially (PR first so its URL flows into the release note):

1. Create PR first: spawn subagent_type: "general-purpose" (model: "opus") preloading report and running ## Create PR. It reads the story file, derives the title, and runs the gh CLI operations. Capture the PR created/updated: <URL> line from its response.
2. Generate release note with PR URL: spawn subagent_type: "general-purpose" (model: "haiku") preloading write-release-note and running it end-to-end. Pass the PR URL obtained in step 1. It reads the story file, generates concise release notes, and writes .workaholic/release-notes/<branch-name>.md.

Capture the PR URL from step 1 for final output.

Phase 6: Commit and Push Release Notes

1. Stage release notes: git add .workaholic/release-notes/
2. Commit: git commit -m "Add release notes for <branch-name>"
3. Push: git push

Report Output Schema

Once orchestration completes, the report is described by:

{
  "story_file": ".workaholic/stories/<branch-name>.md",
  "release_note_file": ".workaholic/release-notes/<branch-name>.md",
  "pr_url": "<PR-URL>",
  "workers": {
    "overview_writer": { "status": "success" | "failed", "error": "..." },
    "section_reviewer": { "status": "success" | "failed", "error": "..." },
    "release_readiness": { "status": "success" | "failed", "error": "..." },
    "release_note_writer": { "status": "success" | "failed", "error": "..." },
    "pr_creator": { "status": "success" | "failed", "error": "..." }
  }
}

Worker Output Mapping

Story sections are populated from the parallel leaf subagents' outputs (each is a general-purpose subagent running the named role):

| Worker role | Sections | Fields | | ----------- | -------- | ------ | | overview-writer | 1, 2, 3 (journey preamble) | overview, highlights[], motivation, journey.mermaid, journey.summary | | section-reviewer | 4, 5, 6, 7 | outcome, historical_analysis, concerns, development_patterns | | release-readiness | 8 | verdict, concerns[], instructions.pre_release[], instructions.post_release[] | | release-note-writer | (separate file) | Writes to .workaholic/release-notes/<branch>.md |

Section 3 (Changes) comes from archived tickets, prefaced by journey content from the overview-writer role. Section 9 (Notes) is optional context.

Judge Carry-Overs

Run by the Phase 1 carry-over judge (a general-purpose subagent that preloads this skill). Inputs: branch name and base branch (usually main).

1. List active carry-overs:

   bash report/scripts/list-active-carryovers.sh
   

   If the JSON output is [], return {"verdicts": []} and stop.

2. For each carry-over in the list, judge whether the work that landed on the current branch (since the carry-over's origin_commit) has resolved it.

   Available evidence:

   • git log --oneline <origin_commit>..HEAD to see commits that landed after the carry-over was filed
   • git diff <origin_commit>..HEAD -- <file mentioned in body> to inspect changes to referenced files
   • Reading files mentioned in the carry-over body (paths in backticks, paths after in)
   • Searching commit subjects for keywords from the carry-over body (git log --oneline --grep='<keyword>' <origin_commit>..HEAD)

   Heuristics for resolved:

   • The file referenced in the body has been deleted, renamed, or refactored such that the concern no longer applies.
   • A commit subject or body explicitly mentions fixing the concern.
   • The behavior described as a risk no longer exists in the current code.

   Heuristics for still_active:

   • No evidence of remediation since origin_commit.
   • The body describes a general suggestion (e.g., "consider parameterizing") without a clear trigger condition.
   • The file still exists and still contains the pattern flagged.

   When in doubt, prefer still_active — false positives (marking resolved when it isn't) lose institutional memory; false negatives (keeping active when it's done) merely re-surface in the next story.

Efficiency: Handling Large Corpora

The corpus can grow large (a backfill from N historical stories produces O(N × items-per-story) items). To stay within reasonable tool-use budgets:

1. Group items by origin_branch first. Items from the same branch tend to reference the same files — cluster them so you can inspect each file once per cluster, not once per item.
2. Within a cluster, deduplicate by referenced file path. Many bullets reference the same file from different angles; one cat plus one git log -- <path> is enough evidence for every bullet that points at that path.
3. Use git log --oneline <origin_commit>..HEAD once per cluster, not per item — the commit list is the same for every bullet that shares an origin commit.
4. Batch the verdicts. Emit verdicts incrementally if helpful, but the final response must be one combined {verdicts: [...]} JSON object.
5. First-run backfill caveat. When the corpus is populated all at once by backfill-carryover.sh, expect a high proportion of resolved verdicts — the items predate the codebase's current structure significantly. This is normal; still-active items remain in .workaholic/concerns/ as passive notes for future judging.

Return a JSON object with the verdicts array:

{
  "verdicts": [
    {
      "path": ".workaholic/concerns/42-foo.md",
      "verdict": "resolved",
      "resolved_by_pr": 47,
      "resolved_by_commit": "abc1234",
      "rationale": "Commit abc1234 removed the inline shell logic this concern flagged."
    },
    {
      "path": ".workaholic/concerns/42-bar.md",
      "verdict": "still_active",
      "rationale": "No commits modified the area this carry-over targets."
    }
  ]
}

Include resolved_by_pr and resolved_by_commit only for resolved verdicts. The orchestrator feeds this to apply-carryover-verdicts.sh (Phase 1) and to the section-reviewer worker so still-active items appear in the new story.

Overview Generation

Generate the four fields consumed by sections 1, 2, and 3 (overview, highlights, motivation, journey) by analyzing commit history for the branch. The overview-writer role (a general-purpose subagent) runs this generation in parallel with the release-readiness and section-reviewer roles.

Collect Commits

Run the bundled script to collect commit information:

bash report/scripts/collect-commits.sh [base-branch]

Default base branch is main.

Output Format (JSON)

{
  "commits": [
    {
      "hash": "abc1234",
      "subject": "Add feature X",
      "body": "Detailed description of the change...",
      "timestamp": "2026-01-15T10:30:00+09:00"
    }
  ],
  "count": 15,
  "base_branch": "main"
}

Content Structure

Generate JSON with four components:

1. Overview

A 2-3 sentence summary capturing the branch essence: main goal, approach taken, what was achieved. Past tense; synthesize from commit subjects.

2. Highlights

Array of 3-5 meaningful changes: extracted from commit subjects, related commits grouped into single highlights, focused on user-visible or architecturally significant changes, ordered by importance not chronology.

3. Motivation

A paragraph synthesizing the "why": what problem or opportunity started this work, why this approach was chosen, what constraints shaped it. Narrative prose, not a list.

4. Journey

Two parts:

• mermaid: A flowchart showing work progression
• summary: 50-100 word summary of development journey

Flowchart Guidelines

flowchart LR
  subgraph Phase1[Initial Setup]
    direction TB
    a1[First step] --> a2[Second step]
  end

  subgraph Phase2[Core Work]
    direction TB
    b1[Third step] --> b2[Fourth step]
  end

  Phase1 --> Phase2

• Use flowchart LR for horizontal timeline
• Use direction TB inside each subgraph for vertical flow
• Group by theme: each subgraph is one concern area
• Connect subgraphs in timeline order
• Maximum 3-5 subgraphs per diagram

Overview Output Format

Return JSON:

{
  "overview": "2-3 sentence summary capturing the branch essence",
  "highlights": [
    "First meaningful change",
    "Second meaningful change",
    "Third meaningful change"
  ],
  "motivation": "Paragraph synthesizing the 'why' from commit context",
  "journey": {
    "mermaid": "flowchart LR\n  subgraph Phase1[Initial Work]\n    direction TB\n    a1[Step 1] --> a2[Step 2]\n  end\n  ...",
    "summary": "50-100 word summary of the development journey"
  }
}

Story Content Structure

The story content (this IS the PR description):

## 1. Overview

[Content from overview-writer `overview` field: 2-3 sentence summary capturing the branch essence.]

**Highlights:**

1. [From overview-writer `highlights[0]}]
2. [From overview-writer `highlights[1]`]
3. [From overview-writer `highlights[2]`]

## 2. Motivation

[Content from overview-writer `motivation` field: paragraph synthesizing the "why" from commit context.]

## 3. Changes

[Content from overview-writer `journey.mermaid` for the flowchart and `journey.summary` for the prose below it.]

```mermaid
[Content from overview-writer `journey.mermaid`]

[Content from overview-writer journey.summary]

Flowchart Guidelines:

• Use flowchart LR for horizontal timeline (subgraphs arranged left-to-right)
• Use direction TB inside each subgraph for vertical item flow
• Group by theme: each subgraph represents one concern or decision area
• Connect subgraphs in timeline order to show work progression
• Use descriptive node labels: id[Description] syntax
• Maximum 3-5 subgraphs per diagram

One subsection per ticket, in chronological order:

3-1. <Ticket title> ([hash](<repo-url>/commit/<hash>))

<1-3 sentence summary of what this ticket changed and why. Focus on the intent and scope of the change rather than enumerating individual files.>

3-2. <Next ticket title> ([hash](<repo-url>/commit/<hash>))

<1-3 sentence summary of what this ticket changed and why.>

...

Changes Guidelines:

• One subsection per ticket (not grouped by theme)
• CRITICAL: Commit hash MUST be a clickable GitHub link, not plain text
  • Wrong: (abc1234) or (<hash>)
  • Correct: ([abc1234](<repo-url>/commit/abc1234))
• Format: ### 3-N. <Title> ([hash](<repo-url>/commit/<hash>))
• Summarize the change in 1-3 sentences per ticket -- describe what was done and why, not individual files
• Focus on intent, scope, and impact rather than enumerating every modified file
• Chronological order matches ticket creation time

4. Outcome

[Summarize what was accomplished. Reference key tickets for details.]

5. Historical Analysis

[Context from related past work. What similar problems were solved before? What patterns emerge from the Related History sections of tickets? If no related tickets exist, write "No related historical context."]

6. Concerns

[Risks, trade-offs, limitations, and forward-looking suggestions discovered during implementation. Each concern is one insight framed as a title, a description of the problem, and how to fix it. This structure is parsed verbatim by extract-carryover.sh on /ship, so follow it exactly.]

Format (one ### block per concern, or "None"):

### <Concise title>

- **Severity:** moderate
- **Description:** <what the problem/risk is> (see [hash](<repo-url>/commit/<hash>) in path/to/file.ext)
- **How to Fix:** <the concrete fix or improvement>

Example:

### Inline shell invocations in drive

- **Severity:** moderate
- **Description:** `drive` still calls `ls -1` inline, violating the Shell Script Principle (see [7eab801](<repo-url>/commit/7eab801) in `plugins/core/skills/drive/SKILL.md`)
- **How to Fix:** Extract the inline invocations into dedicated navigator scripts under the drive skill's `scripts/` directory

Guidelines:

• Severity is a label, not a number: urgent (act now), moderate (should fix), or low (nice-to-have). Default moderate.
• Reference the commit hash from section 3 and the file path where readers should investigate, inside the Description.
• Keep Description and How to Fix to one paragraph each.
• Carried-over concerns (from still_active verdicts) are prepended here as ### blocks, with their title prefixed (carried from PR #N) and their original severity preserved.
• Write "None" if nothing to report.

7. Successful Development Patterns

[Effective patterns discovered during this branch's development that are worth preserving as institutional knowledge.]

Format: Bullet list with pattern description and context.

Example:

• Consolidating 12 skill directories into 4 cohesive units improved navigability without losing behavioral content -- naming skills after their consuming commands creates a discoverable one-to-one mapping
• Running three discovery agents in parallel (history, source, ticket) before writing specs ensures comprehensive context without sequential bottlenecks
• Extracting shell logic into skill scripts rather than inline conditionals prevented exit code 127 failures from path resolution issues

Guidelines:

• Focus on patterns that worked well, not problems encountered (those belong in Concerns)
• Each pattern should be specific enough to be actionable in future branches
• Include the reasoning ("why it worked") not just the action ("what was done")
• Extract from ticket Considerations (positive observations), Final Reports (what went well), and Implementation Steps (approaches that proved effective)
• Categories to consider: architectural decisions, testing strategies, refactoring approaches, collaboration patterns, tooling choices
• Write "None" if no noteworthy patterns emerged

8. Release Preparation

Verdict: [Ready for release / Needs attention before release]

8-1. Concerns

• [List any concerns from release-readiness analysis]
• Or "None - changes are safe for release"

8-2. Pre-release Instructions

• [Steps to take before running /release]
• Or "None - standard release process applies"

8-3. Post-release Instructions

• [Steps to take after release]
• Or "None - no special post-release actions needed"

**Release-readiness input:**

The release-readiness JSON is produced by the release-readiness role — a `general-purpose` subagent the command spawns in parallel during Phase 2. The JSON contains:

```json
{
  "releasable": true/false,
  "verdict": "Ready for release" / "Needs attention before release",
  "concerns": [],
  "instructions": {
    "pre_release": [],
    "post_release": []
  }
}

Format this JSON into section 8.

## 9. Notes

Additional context for reviewers or future reference.

Story Frontmatter

Create .workaholic/stories/<branch-name>.md with YAML frontmatter:

---
branch: <branch-name>
tickets_completed: <count of tickets>
---

Writing Guidelines

• Write in third person ("The developer discovered..." not "I discovered...")
• Connect tickets into a narrative arc, not a list
• Highlight decision points and trade-offs
• Keep Motivation/Journey/Outcome concise (Journey: 50-100 words)
• Changes section: one entry per ticket, brief descriptions
• Historical Analysis/Concerns can be "None" if empty

Updating Stories Index

Update .workaholic/stories/README.md to include the new story:

• Add entry: - [<branch-name>.md](<branch-name>.md) - Brief description of the branch work

Create PR

Create or update a GitHub pull request using the story file as PR content.

Derive PR Title

Extract the first item from the Summary section of the story file:

## 1. Summary

1. First meaningful change

Use that first item as the title. If multiple items exist, append "etc" (e.g., "Add dark mode toggle etc").

Create or Update PR

Run the bundled script:

bash report/scripts/create-or-update.sh <branch-name> "<title>"

What the Script Does

1. Strips YAML frontmatter via strip-frontmatter.sh from .workaholic/stories/<branch-name>.md
2. Writes clean content to /tmp/pr-body.md
3. Checks if PR exists for the branch
4. Creates new PR or updates existing one
5. Outputs the result in required format

Strip Frontmatter Script

A reusable script for removing YAML frontmatter from any markdown file:

bash report/scripts/strip-frontmatter.sh <file>

Outputs clean markdown body to stdout. Handles files with frontmatter, without frontmatter (pass-through), and empty files. Only strips frontmatter starting on line 1 -- content --- separators elsewhere are preserved.

PR Output Format

Exactly one line:

PR created: <URL>

or

PR updated: <URL>

This output format is required by the story command.

Assess Release Readiness

Analyze a branch to determine if it's ready for release.

Analysis Tasks

1. Review code changes: Check git diff main..HEAD for:

   • Incomplete work (TODO, FIXME, XXX comments in new code)
   • Security concerns (hardcoded secrets, credentials)
   • Runtime errors or obvious bugs

2. Check for blocking issues:

   • Tests failing (if tests exist)
   • Type errors (if type checking exists)
   • Missing files referenced in code

3. Identify actionable items (not theoretical concerns):

   • Documentation that needs updating
   • Version numbers to bump
   • Files to stage/commit before release

What NOT to Flag

• "Breaking changes" for command renames - users adapt
• API changes in a plugin - plugins are configuration, not APIs
• Internal refactoring - doesn't affect users
• Theoretical upgrade concerns - users pull fresh versions

Release Readiness Output Format

Return JSON:

{
  "releasable": true,
  "verdict": "Ready for release",
  "concerns": [],
  "instructions": {
    "pre_release": [],
    "post_release": []
  }
}

Or if issues found:

{
  "releasable": false,
  "verdict": "Needs attention before release",
  "concerns": [
    "Found TODO comment in src/foo.ts",
    "Tests failing in commands/drive.md"
  ],
  "instructions": {
    "pre_release": ["Fix failing tests", "Remove TODO comments"],
    "post_release": []
  }
}

Release Readiness Guidelines

• Focus on issues that actually block releases
• Provide actionable instructions, not theoretical warnings
• "Breaking change" is rarely a real concern for plugins
• Empty concerns array is the happy path, not a failure
• If it doesn't require action, don't flag it