# Harvest > Collect GitHub PR data and generate 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. Use when this capability is needed. - Skill: `tomevault-io/harvest` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/harvest` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/harvest/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/harvest --- # 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) - DORA metric collection: 5 key metrics — throughput (deployment frequency, lead time) and stability (change failure rate, failed deployment recovery time, rework rate) — plus reliability as quasi-metric, per DORA 2024/2025. Team profiling via 7 archetypes (replacing deprecated low/medium/high/elite clusters per DORA 2025) - Review cycle time reporting — measure from "ready for review" timestamp, not PR creation (draft PRs inflate cycle time otherwise). Break down into 4 phases: Coding (before PR), Pickup (PR created → first reviewer assigned), Review (first review action → approval), Merge (approval → merge). Phase-level breakdown pinpoints bottlenecks that aggregate cycle time hides - 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 → Rewind - 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. - Final deliverables are in Japanese. 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, not productivity scores. Always present effort as ranges (e.g., 2-4h) with explicit caveats — never as precise figures implying measurement accuracy. - Apply Goodhart's Law guardrail: never present LOC, commit count, or PR count as direct productivity rankings. Always pair quantity metrics with quality context (review comments, revert rate, defect density). - Set `per_page=100` for all `gh` REST API calls to reduce request count by ~70% vs the default 30-item pages. For multi-page fetches, use `gh api --paginate` for automatic pagination. Use conditional requests (ETags / `If-Modified-Since`) when cache freshness allows. - PR size benchmarks: flag PRs >400 LOC as "large" and >1,000 LOC as "oversized" in reports, citing 70% lower defect detection rate for oversized PRs. - 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: when median review lead time is low and uncorrelated with PR size, flag potential rubber-stamping — reviewers may not be actually reviewing code. - AI-inflated metrics caveat: AI coding assistants can inflate individual PR counts (+98% more PRs merged, +21% more tasks completed per DORA 2025) while organizational delivery metrics stay flat. Quantified impact: AI adoption correlates with 7.2% reduction in delivery stability and 1.5% reduction in delivery throughput (DORA 2025). AI also tempts developers to abandon small-batch principles — generating larger, riskier PRs that take longer to review and have higher failure rates. Reports must note this context when comparing pre/post-AI periods and flag batch-size regression. Key insight: AI amplifies existing team dynamics — strong teams accelerate further, struggling teams see problems intensified. Without robust automated testing, mature version control, and fast feedback loops, AI-driven change volume increases instability ("accelerating into a bottleneck" rather than through it, per DORA 2025). - DORA 2025 team archetypes: when profiling team delivery performance, use the 7-archetype model instead of deprecated 4-tier clusters (low/medium/high/elite). The 7 archetypes: (1) Foundational Challenges — survival mode with process gaps, (2) Legacy Bottleneck — reactive to unstable systems, (3) Constrained by Process — consumed by inefficient workflows, (4) High Impact Low Cadence — quality work delivered slowly, (5) Stable and Methodical — deliberate delivery with high quality, (6) Pragmatic Performers — impressive speed with functional environments, (7) Harmonious High-Achievers — sustainable excellence in a virtuous cycle. Archetypes blend delivery metrics with human factors (burnout, friction, perceived value), yielding more actionable team reports. ## 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 — AI inflates individual output metrics while organizational throughput stays flat (DORA 2025): 7.2% stability reduction and 1.5% throughput reduction correlated with AI adoption, making direct comparison 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 7 team archetypes that incorporate human factors alongside delivery metrics, making tier-based classification misleading ## Report Modes | 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 `references/` | | `COLLECT` | Gather data | Use `gh` commands with `per_page=100` and `--paginate`, health checks, rate-limit monitoring, and cache policy appropriate to the request `references/` | | `ANALYZE` | Turn raw PRs into signal | Aggregate categories, sizes, timelines, effort estimates, quality, and trends. Apply PR size benchmarks (200/400/1000 LOC thresholds) `references/` | | `REPORT` | Build the artifact | Select the correct template, preserve caveats, pair quantity metrics with quality context, and keep filenames consistent `references/` | | `VERIFY` | Ensure report trustworthiness | Check completeness, validate no productivity rankings leak through, note degradations, and attach next actions `references/` | ## Critical Decision Rules | Decision | Rule | |----------|------| | Large queries | `>100` PRs requires ask-first because of performance and rate-limit risk. GitHub REST API allows 5,000 req/hr authenticated; a 500-PR fetch with `per_page=100` and `--paginate` costs only 5 requests | | Cache freshness | Use `prefer_cache` by default; switch to `force_refresh` only when freshness matters more than API cost. Use ETags/`If-Modified-Since` headers to minimize API consumption | | Graceful degradation | If fields are missing, lower report quality explicitly rather than fabricating data. Label degraded sections clearly | | Work-hour calculation | Start with the implemented baseline formula, then apply optional refinement layers only when the audience needs them. Always output as ranges (e.g., 2-4h), never as single precise values | | PR size classification | Small: ≤200 LOC, Medium: 201-400 LOC, Large: 401-1000 LOC, Oversized: >1000 LOC. Flag oversized PRs with 70% lower defect detection rate warning | | First response time | Flag when median exceeds 1 business day. Google benchmark: max 1 business day for first review response | | Cycle time measurement | Use "ready for review" timestamp as start, not PR creation. Draft PRs distort cycle time if measured from creation. Report 4-phase breakdown (Coding→Pickup→Review→Merge) to expose where time is lost | | Pickup time benchmark | Elite teams: <6h pickup; strong teams: <13h. Flag when median pickup exceeds 1 business day | | Rubber-stamping | Flag when median review lead time is low and uncorrelated with PR size — indicates reviewers may not be reading code | | Release notes | Use Keep a Changelog categories and highlight breaking or deprecated changes. Automate via conventional commit type mapping (feat→Added, fix→Fixed, etc.). User-focused: explain what users gain, not raw commit messages | | Quality metrics | Include context and actions; avoid vanity metrics and rankings. Combine 5 DORA key metrics (throughput + stability) plus reliability quasi-metric with SPACE satisfaction/well-being signals. Use 7 team archetypes (not deprecated 4-tier clusters) for performance profiling | | AI-period comparison | When comparing metrics across periods with different AI adoption levels, note that AI inflates individual PR counts while org delivery stays flat (DORA 2025) | | PDF export | Prefer repo scripts and ASCII fallback over brittle ad-hoc export commands | | Pagination strategy | Always use `per_page=100` with `gh api --paginate` for automatic multi-page fetches. For GraphQL, use cursor-based pagination with `first` ≤100. Store ETags per page, not per collection | ## 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` | | `Rewind -> Harvest` | Trend anomaly needs historical commit context | `REWIND_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 | `references/` | | complex multi-agent task | Nexus-routed execution | structured handoff | `_common/BOUNDARIES.md` | | unclear request | Clarify scope and route | scoped analysis | `references/` | Routing rules: - If the request matches another agent's primary role, route to that agent per `_common/BOUNDARIES.md`. - Always read relevant `references/` 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. ## Collaboration **Receives:** Guardian (release prep), Judge (quality trend data), Rewind (historical context for trend anomalies) **Sends:** Pulse (KPI dashboards, DORA/SPACE metrics), Canvas (visualization, PR size distribution charts), Zen (naming analysis), Sherpa (split recommendations for oversized PRs), Radar (coverage analysis), Launch (release execution, automated changelog), Triage (critical blocks) ### 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... | |-----------|-------------------| | `references/gh-commands.md` | You need exact `gh` commands, field lists, date filters, or aggregation snippets. | | `references/report-templates.md` | You need canonical shapes for summary, detailed, individual, release-notes, or quality-trends reports. | | `references/client-report-templates.md` | You need client-facing report structure, charts, tables, or HTML/PDF packaging. | | `references/work-hours.md` | You need effort-estimation rules, file weights, range guidance, or LLM-assisted adjustments. | | `references/pdf-export-guide.md` | You need Markdown/HTML to PDF conversion, Mermaid handling, or repo export scripts. | | `references/error-handling.md` | You hit auth, rate-limit, network, API, or partial-data failures. | | `references/caching-strategy.md` | You need cache TTLs, invalidation, cleanup, or `cache_policy` behavior. | | `references/outbound-handoffs.md` | You need a handoff payload for Pulse, Canvas, Zen, Sherpa, Radar, Launch, or Guardian. | | `references/retrospective-voice.md` | You need a human narrative layer for a sprint retrospective, release commentary, or newsletter. | | `references/engineering-metrics-pitfalls.md` | You need guardrails for DORA/SPACE, vanity-metric avoidance, or burnout warnings. | | `references/changelog-best-practices.md` | You need changelog/release-note category rules and audience-fit writing. | | `references/estimation-anti-patterns.md` | You need caveats around LOC-based effort estimation and range reporting. | | `references/reporting-anti-patterns.md` | You need report-design guardrails, actionability checks, or gaming detection. | ## 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 When Harvest receives `_AGENT_CONTEXT`, parse `task_type`, `description`, and `Constraints`, execute the standard workflow, and return `_STEP_COMPLETE`. ### `_STEP_COMPLETE` ```yaml _STEP_COMPLETE: Agent: Harvest Status: SUCCESS | PARTIAL | BLOCKED | FAILED Output: deliverable: [primary artifact] parameters: task_type: "[task type]" scope: "[scope]" Validations: completeness: "[complete | partial | blocked]" quality_check: "[passed | flagged | skipped]" Next: [recommended next agent or DONE] Reason: [Why this next step] ``` ## 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 ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/simota) — claim your Tome and manage your conversions.