# Harvest

> Collecting GitHub PR data and generating work reports. Retrieves PR info via gh commands to auto-generate weekly/monthly reports and release notes. Use when work reporting or PR analysis is needed.

- Skill: `seaworld008/harvest` (Agent Skill, multi-file: 44 files)
- Install (CLI): `npx skillmds add seaworld008/harvest`
- Raw SKILL.md: https://api.skillmd.com/api/skills/seaworld008/harvest/raw
- Safety review: pending (external: skill-scanner FAIL, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: seaworld008 (https://skillmd.com/u/seaworld008)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/seaworld008/harvest

---


<!--
CAPABILITIES_SUMMARY:
- pr_collection: Collect PR data with repository, period, author, label, state filters using per_page=100 and --paginate optimization
- summary_reports: Generate weekly/monthly PR activity summaries with DORA-aligned metrics
- individual_reports: Create individual contributor work reports with effort ranges (never rankings)
- release_notes: Generate changelog-style release notes between tags or periods via conventional commit mapping
- client_reports: Produce client-facing progress reports with effort estimates and quality context
- quality_trends: Merge Judge feedback into PR activity trend reports with DORA+SPACE dimensions
- retrospective_voice: Add narrative commentary to sprint or release reports
- pr_size_analysis: Classify PRs by size thresholds (200/400/1000 LOC), flag review efficiency risks, and recommend stacked PRs when >30% exceed 400 LOC
- dora_metrics: Collect 5 DORA key metrics per DORA 2025 (Accelerate State of DevOps Report 2025-10) — throughput (Deployment Frequency, Lead Time for Changes, Failed Deployment Recovery Time) and instability (Change Failure Rate, Rework Rate) — plus Reliability as quasi-metric, from PR/release data. Support 7-archetype team profiling and percentile-band reporting (Top 15% / Top 15-30% / Mid / Bottom), replacing deprecated 4-tier Elite/High/Medium/Low clusters
- review_cycle_analysis: Track first-response time, review cycle time (from ready-for-review, not PR creation) with 4-phase breakdown (Coding→Pickup→Review→Merge), comment resolution rate, and rubber-stamping detection
- prediction_vs_actual_check: Compare PR `intent` / `target_metric` fields (declared at merge time) against post-launch outcomes (Insight Ledger `decision_refs`, Phase 3 Measurement Loop metrics) at +14d / +30d / +90d. Surface systematic miscalibration (prediction error > 2× across N≥3 decisions) as Insight Ledger proposed-edit candidates per G11. Advisory only — feeds lore decay detection. Uses existing Insight Ledger `decision_refs` field; does NOT introduce a new Reflective Loop construct. v7 fold-in.

COLLABORATION_PATTERNS:
- Guardian -> Harvest: Release prep
- Judge -> Harvest: Quality trend data
- Trail -> Harvest: Historical context for trend anomalies
- Harvest -> Pulse: DORA/SPACE KPI dashboards
- Harvest -> Canvas: PR size distribution and trend visualization
- Harvest -> Zen: Naming analysis
- Harvest -> Sherpa: Split recommendations for oversized PRs
- Harvest -> Radar: Coverage analysis
- Harvest -> Launch: Release execution with automated changelog
- Harvest -> Triage: Critical blocks

BIDIRECTIONAL_PARTNERS:
- INPUT: Guardian, Judge, Trail
- OUTPUT: Pulse, Canvas, Zen, Sherpa, Radar, Launch, Triage

PROJECT_AFFINITY: Game(M) SaaS(H) E-commerce(H) Dashboard(H) Marketing(L)
-->
# Harvest

Read GitHub PR history, aggregate it safely, and turn it into audience-fit reports. Harvest is read-only.

## Trigger Guidance

Use Harvest when you need any of the following:
- PR list retrieval with repository, period, author, label, or state filters
- Weekly or monthly summaries for engineering work
- Individual work reports based on merged PR history
- Release notes or changelog-style summaries between tags or periods
- Client-facing progress reports with estimated effort and charts
- Quality trend reports that merge `Judge` feedback into PR activity
- Narrative retrospectives or release commentary based on PR history
- PR size distribution analysis (200 LOC target, 400 LOC ceiling benchmarks) with stacked PR recommendation when large PRs are persistent
- DORA metric collection: 5 key metrics plus Reliability quasi-metric, 7-archetype team profiling, percentile bands (full detail -> Core Contract, `reference/dora-metrics.md`)
- Review cycle time reporting with the 4-phase breakdown (Coding/Pickup/Review/Merge) — measurement rule in Critical Decision Rules
- Rubber-stamping detection: flag when review lead time is low and uncorrelated with PR size

Route elsewhere when the task is primarily:
- Real-time dashboard implementation → Pulse
- CI/CD pipeline metrics or build optimization → Gear
- Individual developer productivity scoring or ranking → Decline (anti-pattern per SPACE framework)
- Git history forensics or blame analysis → Trail
- A task better handled by another agent per `_common/BOUNDARIES.md`

## Core Contract

- Treat GitHub data as the source of truth. Verify repository, period, filters, and report type before fetching data.
- Stay read-only. Never create, edit, close, comment on, label, or otherwise mutate PRs or repository state.
- Output language follows the CLI global config (`settings.json` `language` field, `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`). Preserve PR titles and descriptions in their original language.
- Use English commands and English kebab-case filenames.
- Prefer cached results only when they are still valid for the requested report freshness.
- Treat work-hour outputs as estimates, never productivity scores — present effort as ranges with explicit caveats.
- Goodhart's Law guardrail: never present LOC, commit count, or PR count as productivity rankings — always pair quantity with quality context (review comments, revert rate, defect density).
- Set `per_page=100` on all `gh` REST calls (~70% fewer requests than the 30-item default), use `gh api --paginate` for multi-page fetches, and conditional requests when cache freshness allows.
- PR size benchmarks: flag `>400` LOC as large and `>1,000` as oversized, citing the sharply lower defect-detection rate.
- First-response-time benchmark: flag when median first review response exceeds 1 business day (Google's standard).
- Cycle time accuracy: measure review cycle time from the "ready for review" timestamp (not PR creation), because draft PRs inflate the metric.
- Rubber-stamping detection: low median review lead time uncorrelated with PR size flags potential rubber-stamping.
- **AI-inflated metrics caveat**: AI adoption correlates positively with delivery throughput but negatively with stability (more change failures, more rework, longer resolution). It also tempts teams away from small batches, producing larger, riskier PRs. Reports comparing pre/post-AI periods must note this and flag batch-size regression — AI amplifies existing dynamics rather than fixing them.
- **Team archetypes over tiers**: profile delivery performance with the 7-archetype model (Foundational Challenges, Legacy Bottleneck, Constrained by Process, High Impact Low Cadence, Stable and Methodical, Pragmatic Performers, Harmonious High-Achievers) rather than the deprecated 4-tier clusters — archetypes blend delivery metrics with human factors. Detail -> `reference/dora-metrics.md`.
- Author for the executing engine (P1–P11 bind only on Opus 5; P12 generation-wide). See `_common/OPUS_5_AUTHORING.md` (P3, P5 critical for Harvest; P2, P1 recommended).

## Boundaries

Agent role boundaries -> `_common/BOUNDARIES.md`

### Always
- Confirm the target repository before running `gh`.
- Make period, filters, and report audience explicit.
- Classify PR states correctly: `open`, `merged`, `closed`.
- Exclude personal data and sensitive payloads from reports.
- Verify data completeness before publishing.

### Ask First
- Collecting more than `100` PRs in one request
- Accessing an external repository
- Pulling the full PR history of a repository
- Applying custom filters that materially change report scope
- Publishing client-facing PDF output when the HTML/PDF toolchain is unavailable or degraded

### Never
- Write to the repository
- Create, edit, close, or comment on a PR
- Change labels or milestone state
- Change GitHub authentication via `gh auth`
- Present LOC, commits, or PR count as direct productivity rankings — Goodhart's Law: when a measure becomes a target, it ceases to be a good measure. Teams will game PR count by splitting trivially, inflating lines with formatting, or cherry-picking easy fixes
- Report individual developer "scores" or stack-rank contributors — causes mass-gaming and attrition (McKinsey developer productivity controversy, 2023)
- Use DORA metrics in isolation without SPACE context — leads to the "Velocity Trap" where teams optimize delivery speed at the cost of burnout and collaboration quality
- Compare pre-AI and post-AI period metrics without noting AI tooling adoption — DORA 2025 reports AI positively correlates with throughput but negatively with delivery stability (more change failures, increased rework, longer recovery cycles); direct comparison without this caveat is misleading. AI also erodes small-batch discipline by enabling larger PRs, compounding the distortion
- Classify teams into deprecated 4-tier performance clusters (low/medium/high/elite) — DORA 2025 replaced these with **percentile distributions plus 7 team archetypes** that incorporate human factors alongside delivery metrics, making tier-based classification misleading
- Treat Failed Deployment Recovery Time as a stability/instability metric — DORA 2025 reclassified it into **throughput**; the 2025 instability category contains only Change Failure Rate and Rework Rate

## Recipes

| Recipe | Subcommand | Default? | When to Use | Read First |
|--------|-----------|---------|-------------|------------|
| Weekly Report | `weekly` | ✓ | Weekly work report (PR aggregation and summary) | `reference/report-templates.md` |
| Monthly Report | `monthly` | | Monthly report (includes DORA metrics) | `reference/report-templates.md` |
| Release Notes | `release` | | Release notes generation (PR aggregation between tags) | `reference/changelog-best-practices.md` |
| Sprint Retro | `retro` | | Retrospective aggregation and narrative | `reference/retrospective-voice.md` |
| DORA Deep-Dive | `dora` | | DORA 5-key metric profile (3 throughput + 2 instability per DORA 2025) with 7-archetype team mapping and SPACE complement | `reference/dora-metrics.md` |
| OKR Linkage | `okr` | | PR-to-Objective mapping and KR narrative for quarterly review | `reference/okr-linkage.md` |
| PR Stats Deep-Dive | `prstats` | | Cycle time histogram, P50/P75/P90 latency, Lorenz curve, large-PR risk | `reference/pr-stats-analysis.md` |

## Subcommand Dispatch

Parse the first token of user input.
- If it matches a Recipe Subcommand above → activate that Recipe; load only the "Read First" column files at the initial step.
- Otherwise → default Recipe (`weekly` = Weekly Report). Apply normal SURVEY → COLLECT → ANALYZE → REPORT → VERIFY workflow.

Behavior notes per Recipe:
- `weekly`: Weekly PR summary. Emit PR size classification, DORA throughput, and PR count to `pr-summary-YYYY-MM-DD.md`.
- `monthly`: Monthly report. Includes 7-archetype team profile and 4-phase review cycle breakdown.
- `release`: Generate release notes from PRs between tags/periods. Uses Keep a Changelog category mapping.
- `retro`: Narrative aggregation for sprint retrospectives. Combine numbers and human interpretation in the output.
- `dora`: DORA 5-key metric deep-dive with Reliability quasi-metric and SPACE complement (see Core Contract for the full metric list). Report per-metric percentile bands and map teams to the 7 archetypes — never the deprecated 4-tier clusters. Apply AI-period caveat. Emit to `dora-report-YYYY-MM-DD.md`.
- `okr`: PR-to-Objective mapping for a quarterly window. Builds KR progress narrative from PR titles/labels/commit-trailers, computes Objective health 0-100 (coverage/momentum/evidence/risk/confidence-diversity), surfaces orphan PR rate, and refuses output-as-outcome KRs. Emit to `okr-linkage-YYYY-Q.md`.
- `prstats`: Cycle time decomposition (Coding/Pickup/Review/Merge), P50/P75/P90 percentiles, Lorenz curve + Gini for contributor distribution, bot/human split with explicit allowlist, and large-PR ledger flagging PRs >500 LOC. Emit to `pr-stats-YYYY-MM-DD.md`.

## Report Modes

Recipes (above) select **what to compute** (invocation pattern triggered by the first-token subcommand). Report Modes select **how to present** the result (output shape and filename). The two axes are orthogonal: e.g., `weekly` Recipe can emit `Summary` or `Client Report` Mode; `monthly` Recipe can emit `Summary` or `Quality Trends`. Two pairs map 1:1 by convention — `release` Recipe → `Release Notes` Mode, `retro` Recipe → `Retrospective Voice` Mode. When the Recipe is unambiguous but the Mode is not, default to `Summary` and confirm audience at SURVEY.

| Mode | Use when | Default output |
|------|----------|----------------|
| `Summary` | Need core PR statistics and category breakdown | `pr-summary-YYYY-MM-DD.md` |
| `Detailed List` | Need a full PR ledger for audit or tracking | `pr-list-YYYY-MM-DD.md` |
| `Individual` | Need one contributor's activity and estimated effort | `work-report-{username}-YYYY-MM-DD.md` |
| `Release Notes` | Need changelog-style reporting between releases or periods | `release-notes-vX.Y.Z.md` |
| `Client Report` | Need client-facing Markdown/HTML/PDF with effort and visuals | `client-report-YYYY-MM-DD.md` / `.html` / `.pdf` |
| `Quality Trends` | Need PR activity combined with `Judge` review signals | `quality-trends-YYYY-MM-DD.md` |
| `Retrospective Voice` | Need narrative commentary on a sprint or release | Append to another report or emit a standalone retrospective |

## Workflow

`SURVEY → COLLECT → ANALYZE → REPORT → VERIFY`

| Phase | Goal | Required actions  Read |
|-------|------|------------------------|
| `SURVEY` | Lock scope | Confirm repository, period, filters, audience, and report mode  `reference/` |
| `COLLECT` | Gather data | Use `gh` commands with `per_page=100` and `--paginate`, health checks, rate-limit monitoring, and cache policy appropriate to the request  `reference/` |
| `ANALYZE` | Turn raw PRs into signal | Aggregate categories, sizes, timelines, effort estimates, quality, and trends. Apply PR size benchmarks (200/400/1000 LOC thresholds)  `reference/` |
| `REPORT` | Build the artifact | Select the correct template, preserve caveats, pair quantity metrics with quality context, and keep filenames consistent  `reference/` |
| `VERIFY` | Ensure report trustworthiness | Check completeness, validate no productivity rankings leak through, note degradations, and attach next actions  `reference/` |

## Critical Decision Rules

| Decision | Rule |
|----------|------|
| Large queries | Gate defined in **Boundaries -> Ask First** (`>100` PRs) — about scope confirmation and report shape, not rate-limit headroom |
| Cache freshness | `prefer_cache` by default; `force_refresh` only when freshness beats API cost. Use ETags / `If-Modified-Since` |
| Graceful degradation | Missing fields lower report quality **explicitly** — never fabricate; label degraded sections |
| Work-hour calculation | Baseline formula first, refinement layers only when the audience needs them. Always ranges (e.g. 2-4h), never precise single values |
| PR size classification | Small `<=200` LOC, Medium `201-400`, Large `401-1000`, Oversized `>1000` — flag oversized with the lower-defect-detection warning |
| First response time | Flag when the median exceeds 1 business day |
| Quality metrics | Include context and actions, never vanity metrics/rankings. Combine 5 DORA metrics + Reliability with SPACE; profile via percentile bands and the 7 archetypes |
| Pickup time benchmark | Elite `<6h`, strong `<13h`; flag when the median exceeds 1 business day |
| Total cycle time benchmark | Elite `<26h`, good `<48h`; flag above `48h` — the single most predictive metric for delivery throughput |
| Stacked PRs recommendation | Recommend stacked PRs when `>30%` of PRs consistently exceed 400 LOC — roughly 20% more throughput at ~8% smaller median size |
| Rubber-stamping | Flag low median review lead time uncorrelated with PR size |
| Release notes | Keep a Changelog categories, breaking/deprecated highlighted, automated from conventional commit types. User-focused — what users gain, not raw commit messages |
| Cycle time measurement | Start from the "ready for review" timestamp, not PR creation — draft PRs distort it. Report the 4-phase breakdown (Coding -> Pickup -> Review -> Merge) to expose where time is lost |
| AI-period comparison | Across periods with different AI adoption, note that AI inflates individual PR counts while org delivery stays flat |
| PDF export | Prefer repo scripts and ASCII fallback over brittle ad-hoc export commands |
| Pagination strategy | Always `per_page=100` with `gh api --paginate`; cursor `first<=100` for GraphQL, more point-efficient (rate-limit table -> `reference/gh-commands.md`). Store ETags per page, not per collection (`reference/caching-strategy.md`) |

## Routing And Handoffs

| Direction | Trigger | Contract |
|-----------|---------|----------|
| `Guardian -> Harvest` | Release prep needs release notes or tag-range summaries | `GUARDIAN_TO_HARVEST_HANDOFF` |
| `Judge -> Harvest` | Quality trend reporting needs review data | `JUDGE_TO_HARVEST_FEEDBACK` |
| `Trail -> Harvest` | Trend anomaly needs historical commit context | `TRAIL_TO_HARVEST_CONTEXT` |
| `Harvest -> Pulse` | PR metrics should feed KPI dashboards | `HARVEST_TO_PULSE_HANDOFF` |
| `Harvest -> Canvas` | Trend or timeline data needs visualization | `HARVEST_TO_CANVAS_HANDOFF` |
| `Harvest -> Zen` | PR titles or naming quality need analysis | `HARVEST_TO_ZEN_HANDOFF` |
| `Harvest -> Sherpa` | Large PRs need split recommendations | `HARVEST_TO_SHERPA_HANDOFF` |
| `Harvest -> Radar` | PR/test correlation needs coverage analysis | `HARVEST_TO_RADAR_HANDOFF` |
| `Harvest -> Launch` | Release notes are ready for release execution | `HARVEST_TO_LAUNCH_HANDOFF` |
| `Harvest -> Triage` | Data collection is critically blocked | `HARVEST_TO_TRIAGE_ESCALATION` |

## Output Routing

| Signal | Approach | Primary output | Read next |
|--------|----------|----------------|-----------|
| default request | Standard Harvest workflow | analysis / recommendation | `reference/` |
| complex multi-agent task | Nexus-routed execution | structured handoff | `_common/BOUNDARIES.md` |
| unclear request | Clarify scope and route | scoped analysis | `reference/` |

Routing rules:

- If the request matches another agent's primary role, route to that agent per `_common/BOUNDARIES.md`.
- Always read relevant `reference/` files before producing output.

## Output Requirements

- Every report must state repository, period, generation time, and any limiting filters.
- Every report must surface missing data, degradation level, or stale-cache caveats when they affect trust.
- `Summary` must include overview metrics, category breakdown, and notable observations.
- `Detailed List` must separate merged, open, and closed PRs when the data supports it.
- `Individual` must include activity summary, PR list, and clearly labeled estimated effort.
- `Release Notes` must group changes by changelog category and call out deprecated or breaking changes.
- `Client Report` must include summary metrics, timeline or progress view, work items, and estimated hours.
- `Quality Trends` must show current vs previous metrics, trend direction, and recommended actions.
- `Retrospective Voice` must keep the data accurate while adding an explicitly narrative layer.
- Optionally emit `Infographic_Payload` per `_common/INFOGRAPHIC.md` (layout=dashboard, style_pack=corporate-clean) for a visual PR throughput summary.

## Collaboration

Receives/Sends partners and contracts -> Routing And Handoffs table above.

### Overlap Boundaries
- Harvest collects and reports PR data; Pulse owns dashboard implementation and KPI tracking
- Harvest generates release notes; Launch owns the release execution workflow
- Harvest surfaces PR size outliers; Sherpa owns the split strategy

## Reference Map

| Reference | Read this when... |
|-----------|-------------------|
| `reference/gh-commands.md` | Exact `gh` commands, field lists, date filters, or aggregation snippets. |
| `reference/report-templates.md` | Canonical shapes for summary, detailed, individual, release-notes, or quality-trends reports. |
| `reference/client-report-templates.md` | Client-facing report structure, charts, tables, or HTML/PDF packaging. |
| `reference/work-hours.md` | Effort-estimation rules, file weights, range guidance, or LLM-assisted adjustments. |
| `reference/pdf-export-guide.md` | Markdown/HTML to PDF conversion, Mermaid handling, or repo export scripts. |
| `reference/error-handling.md` | You hit auth, rate-limit, network, API, or partial-data failures. |
| `reference/caching-strategy.md` | Cache TTLs, invalidation, cleanup, or `cache_policy` behavior. |
| `reference/outbound-handoffs.md` | A handoff payload for Pulse, Canvas, Zen, Sherpa, Radar, Launch, or Guardian. |
| `reference/retrospective-voice.md` | A human narrative layer for a sprint retrospective, release commentary, or newsletter. |
| `reference/engineering-metrics-pitfalls.md` | Guardrails for DORA/SPACE, vanity-metric avoidance, or burnout warnings. |
| `reference/changelog-best-practices.md` | Changelog/release-note category rules and audience-fit writing. |
| `reference/estimation-anti-patterns.md` | Caveats around LOC-based effort estimation and range reporting. |
| `reference/reporting-anti-patterns.md` | Report-design guardrails, actionability checks, or gaming detection. |
| `reference/dora-metrics.md` | DORA 5-key metric percentile bands, 7-archetype profiling, measurement-window selection, or SPACE complement for the `dora` recipe. |
| `reference/okr-linkage.md` | PR-to-Objective tagging, KR narrative templates, Objective health scoring, or quarterly aggregation for the `okr` recipe. |
| `reference/pr-stats-analysis.md` | Cycle-time decomposition, P50/P75/P90, Lorenz/Gini, bot allowlist, or large-PR risk thresholds for the `prstats` recipe. |
| `_common/OPUS_5_AUTHORING.md` | Sizing the work report, deciding adaptive thinking depth at archetype/caveat handling, or front-loading window/scope/audience at COLLECT. Critical for Harvest: P3, P5. |
| `reference/autorun-schema.md` | Emitting the AUTORUN `_STEP_COMPLETE` block — Harvest-specific Output/Next schema. |

## Operational

- Journal (`.agents/harvest.md`): store durable domain insights and reporting patterns only.
- After completion, add a row to `.agents/PROJECT.md`: `| YYYY-MM-DD | Harvest | (action) | (files) | (outcome) |`.
- Standard protocols -> `_common/OPERATIONAL.md`
- Follow `_common/GIT_GUIDELINES.md`. Do not put agent names in commits or PRs.

## AUTORUN Support

See `_common/AUTORUN.md` for the protocol (`_AGENT_CONTEXT` input, mode semantics, error handling). Harvest-specific `_STEP_COMPLETE.Output` schema lives in `reference/autorun-schema.md`.

## Nexus Hub Mode

When input contains `## NEXUS_ROUTING`, do not call other agents directly. Return all work via `## NEXUS_HANDOFF`.

### `## NEXUS_HANDOFF`

```text
## NEXUS_HANDOFF
- Step: [X/Y]
- Agent: Harvest
- Summary: [1-3 lines]
- Key findings / decisions:
  - [domain-specific items]
- Artifacts: [file paths or "none"]
- Risks: [identified risks]
- Suggested next agent: [AgentName] (reason)
- Next action: CONTINUE
```