delivery-reporting（交货报告）

Delivery Reporting Skill

Creating visual executive presentations that showcase squad deliveries and business value.

⚠️ CRITICAL: Quality Over Speed

This skill prioritizes depth over velocity.

FORBIDDEN:

• ❌ Using general-purpose agent for parallel speed
• ❌ Rushing analysis to meet arbitrary deadlines
• ❌ Reading only PR titles without code analysis
• ❌ Skipping Gate 2.5 (Deep Code Analysis)

REQUIRED:

• ✅ Sequential deep analysis per repository
• ✅ Code reading with domain-specialized agents
• ✅ Real data, never estimates
• ✅ Business value extracted from actual code changes

Purpose

This skill provides a framework for:

• Squad delivery reports (engineering + product + design)
• Visual HTML slide presentations
• Deep code analysis using specialized agents
• Business value extraction from Git repositories
• Quarterly/monthly showcase of releases and features
• Stakeholder-facing delivery summaries

Key Difference from executive-reporting:

• executive-reporting: Portfolio/project status (PMO focus, RAG/SPI/CPI metrics)
• delivery-reporting: Squad deliveries (technical focus, deep code analysis, releases/PRs/features)

Visual Identity Options

MUST ask user for visual identity preference when generating delivery reports:

Option 1: Lerian Studio (Default)

visual_identity:
  background: "#0C0C0C"  # Black
  text_primary: "#FFFFFF"  # White
  text_secondary: "#CCCCCC"  # Light gray
  accent: "#FEED02"  # Lerian Yellow
  font_family: "Poppins, system-ui, sans-serif"

Option 2: Ring Neutral (Corporate)

visual_identity:
  background: "#F5F5F5"  # Very light gray
  text_primary: "#1A1A1A"  # Soft black
  text_secondary: "#666666"  # Medium gray
  accent: "#0066CC"  # Professional blue
  font_family: "system-ui, -apple-system, sans-serif"

Option 3: Custom (User-Provided)

User provides their own color scheme and fonts.

MANDATORY: Always ask which option before proceeding with report generation.

Delivery Reporting Gates

Gate 1: Input Collection

Objective: Gather required information for report generation

Actions:

1. Collect period (start date, end date)
2. Collect repository list
3. Collect business context (optional)
4. Select visual identity (Lerian/Ring/Custom)

User Input Format:

**Período de Análise:**
- Data de Início: AAAA-MM-DD
- Data de Fim: AAAA-MM-DD

**Repositórios para Análise:**
- org/repo-name-1 (e.g., LerianStudio/midaz)
- org/repo-name-2 (e.g., LerianStudio/product-console)
- OR full URLs: https://github.com/org/repo

**Contexto de Negócio (Opcional):**
- [Text with project names, clients, strategic context]

**Identidade Visual:**
- [lerian/ring/custom]

Repository Format Rules:

CRITICAL: Agent MUST validate repository format and provide clear error if invalid.

Output: docs/pmo/delivery-reports/{date}/inputs.md

Gate 2: Repository Analysis

Objective: Extract technical data from Git repositories

Actions for Each Repository:

1. Tags/Releases: List all tags created (git tag, gh release list)
2. PRs Merged: List merged PRs with titles/descriptions (gh pr list --state merged)
3. Commits: Count commits on main branch (git log --oneline)
4. Active Branches: List branches with recent commits not yet merged
5. Release Notes: Read GitHub Release notes if available
6. README: Extract business description from README.md

Data Gathering Commands:

# For each repo:
cd /path/to/repo
git fetch --all --tags
git tag --sort=-creatordate  # List tags
gh release list --limit 100  # Release notes
gh pr list --state merged --search "merged:>=YYYY-MM-DD" --json number,title,body
git log --oneline --since="YYYY-MM-DD" --until="YYYY-MM-DD" main
git branch -r --sort=-committerdate  # Active branches

Output: docs/pmo/delivery-reports/{date}/analysis-data.md

Gate 2.5: Deep Code Analysis (MANDATORY)

⚠️ CRITICAL: This gate CANNOT be skipped for speed.

Objective: Understand actual code changes and their impact using specialized agents

Core Principle: Quality Over Speed

FORBIDDEN:

• ❌ Using general-purpose agent for parallel speed
• ❌ Reading only PR titles without code analysis
• ❌ Skipping this gate to save time
• ❌ Estimating impact without reading code

REQUIRED:

• ✅ Use specialized agents per repository type
• ✅ Read actual code diffs of significant PRs
• ✅ Analyze architectural decisions
• ✅ Extract true business impact from code

Agent Selection Per Repository:

Analysis Workflow:

For each repository:

1. **Identify Technology Stack**
   - Read package.json, go.mod, requirements.txt
   - Determine primary language

2. **Dispatch Appropriate Specialized Agent**
   Task(
     subagent_type="ring:backend-engineer-golang",  # or appropriate
     prompt="""
     Analyze {repo_name} deliveries for period {start} to {end}.

     PRs to analyze: {pr_list}

     For each significant PR (>100 lines changed):
     1. Read code diff
     2. Identify technical changes
     3. Assess architecture/design decisions
     4. Extract business impact
     5. Identify quality improvements

     Provide business value statements suitable for executives.
     Format: "What was built + Why it matters + Who benefits"
     """
   )

3. **Aggregate Agent Insights**
   - Collect business value statements from all agents
   - Group by theme/product
   - Prioritize by impact level

4. **Verify Understanding**
   - Spot-check agent analysis by reading key diffs
   - Confirm business value accuracy
   - Add missing context

Time Expectations (NON-NEGOTIABLE):

• 1 repository = 5-10 minutes of deep analysis
• 8 repositories = 40-80 minutes total
• Quality cannot be rushed

Output: docs/pmo/delivery-reports/{date}/deep-code-analysis.md

Quality Checklist:

• Specialized agent used for each repo type
• Significant PRs analyzed with code reading
• Business value extracted from code, not just titles
• Agent insights aggregated and verified
• No "too vague" statements (e.g., "various improvements")

If pressured to skip this gate:

BLOCKER: Attempt to skip deep code analysis
Reason: "Too many repos" / "Takes too long" / "Use general-purpose"
Response: Deep analysis is MANDATORY. Quality over speed.
Action: Will proceed with proper specialized agent analysis.

Gate 3: Business Value Extraction

Objective: Transform technical changes into business value statements

Actions:

1. Analyze PR titles/descriptions for business intent
2. Group deliveries by theme (new features, security, performance, etc.)
3. Identify first releases (v1.0.0 = new product)
4. Extract client/user impact from commit messages
5. Identify "work in progress" from active branches

Business Value Framework:

• What was built? (Technical)
• Why does it matter? (Business impact)
• Who benefits? (Users, clients, team)

Example Transformation:

• ❌ Bad: "Updated library X to version Y"
• ✅ Good: "Enhanced login security by updating authentication library, protecting user data from vulnerability Z"

Output: docs/pmo/delivery-reports/{date}/business-value.md

Gate 4: Slide Generation

Objective: Create visual HTML presentation

Slide Structure (8-12 slides):

1. Capa (Cover Slide)

- Title: "Entregas de Produtos [Squad/Company Name]" - Subtitle: "Resumo Executivo" - Period: "DD a DD de MÊS de YYYY" (Portuguese format, e.g., "12 a 31 de Janeiro de 2026") - Key metrics: Novos Produtos, Releases, PRs, Commits - Agility metric: "Média de X releases por dia"

1. Resumo Executivo (Executive Summary)

- One paragraph summary - 3-4 main highlights

3-N. Detalhamento por Produto/Tema (Detail Slides)

• Group deliveries by product or theme
• 2-3 bullets per product with business value
• Connect technical changes to business outcomes

N. Próximos Passos (Next Steps)

• Based on active branches analysis
• 2-3 upcoming initiatives

N+1. Encerramento (Closing)

• Thank you / Questions slide

HTML Template Structure:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Delivery Report</title>
  <style>
    /* CSS with selected visual identity */
    body { background: var(--bg-color); font-family: var(--font); }
    .slide { min-height: 100vh; padding: 4rem; }
    /* ... responsive layout, print styles ... */
  </style>
</head>
<body>
  <div class="slide cover"><!-- Cover content --></div>
  <div class="slide summary"><!-- Summary content --></div>
  <!-- Product/theme slides -->
  <div class="slide next-steps"><!-- Next steps --></div>
  <div class="slide closing"><!-- Closing --></div>
</body>
</html>

Output: docs/pmo/delivery-reports/{date}/delivery-report-{date}.html

Gate 5: Review and Delivery

Objective: Validate quality and deliver

Actions:

1. Verify all metrics are accurate
2. Check business value statements are non-technical
3. Test HTML rendering (open in browser)
4. Verify print-to-PDF works correctly
5. Deliver file to user

Quality Checklist:

• Metrics calculated correctly
• Business value statements are clear
• No overly technical jargon
• Visual identity applied correctly
• HTML renders properly in browser
• Print to PDF works (for sharing)

Delivery:

• HTML file ready for browser viewing
• Instructions for PDF export: "Open in browser → Print → Save as PDF"

Anti-Rationalization Table

See shared-patterns/anti-rationalization.md for universal anti-rationalizations.

Delivery Reporting-Specific Anti-Rationalizations

Pressure Resistance

See shared-patterns/pressure-resistance.md for universal pressure scenarios.

Delivery Reporting-Specific Pressures

Blocker Criteria - STOP and Report

ALWAYS pause and report blocker for:

Cannot Be Overridden

The following requirements are NON-NEGOTIABLE:

If user insists on violating these:

1. Escalate to orchestrator
2. Do NOT generate report without proper analysis
3. Document the request and your refusal

Severity Calibration

When determining delivery significance:

Lead with CRITICAL and HIGH. Aggregate MEDIUM and LOW. Never inflate significance.

Output Format

Final Deliverable

File: docs/pmo/delivery-reports/{date}/delivery-report-{date}.html

Self-Contained HTML:

• No external dependencies
• Inline CSS with selected visual identity
• Responsive design (desktop/tablet/mobile)
• Print-optimized (for PDF export)
• Navigation between slides (arrow keys/click)

Execution Report

Base metrics per shared-patterns/execution-report.md:

Delivery Reporting-Specific Details

When Delivery Report is Not Needed

If no significant deliveries in period:

Signs of minimal activity:

• Zero releases/tags created
• Fewer than 5 PRs merged
• Only maintenance commits (no new features)
• No active branches with work in progress

Action: Report "Low activity period" with exact metrics, suggest extending date range or focusing on other squads.

CRITICAL: Do NOT manufacture content when activity is minimal. Report reality.

Example Business Value Statements

Bad (Too Technical)

• "Migrated from Express 4.x to Express 5.x"
• "Implemented Redis caching layer"
• "Updated TypeScript to 5.3"

Good (Business Value)

• "Improved API response time by 40% through caching optimization, enhancing user experience"
• "Modernized backend framework to latest security standards, protecting customer data"
• "Reduced technical debt by updating core dependencies, improving system stability"

Metrics Calculation Examples

Releases per Day

releases_per_day = total_releases / days_in_period
Example: 15 releases / 20 days = 0.75 releases/day
Display: "Média de 0.75 releases por dia" ou "~1 release por dia"

Release Distribution

stable_releases = tags matching v*.*.* (not beta/rc)
beta_releases = tags matching *-beta.*
rc_releases = tags matching *-rc.*

Project Status Classification

- New Product: first v1.0.0 tag in period
- Active Development: multiple releases (>= 3)
- Maintenance: few commits, no major releases
- Inactive: no commits in period

Related Skills

• executive-reporting: For portfolio/project status reports (PMO focus)
• portfolio-planning: For strategic portfolio planning
• project-health-check: For individual project health assessment

Integration with Executive Reporter Agent

This skill dispatches the ring:delivery-reporter agent to perform repository analysis and HTML generation.

Agent Invocation:

Task tool:
  subagent_type: "ring:delivery-reporter"
  prompt: |
    Create delivery report for period {start_date} to {end_date}.
    Repositories: {repo_list}
    Business context: {context}
    Visual identity: {identity}

Agent Responsibilities:

• Git/GitHub data extraction
• Business value analysis
• HTML slide generation
• Quality validation