@lovehlmmm/primekit 1.0.0

package/skills/research/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: pk:research
+description: "Research technical solutions, analyze architectures, gather requirements thoroughly. Use for technology evaluation, best practices research, solution design, scalability/security/maintainability analysis."
+user-invocable: true
+when_to_use: "Invoke for deep technical research before implementation."
+category: utilities
+keywords: [research, evaluation, analysis, solutions]
+license: MIT
+argument-hint: "[topic] [--ultra] [--yagni]"
+metadata:
+  author: primekit
+  version: "1.1.0"
+---
+
+# Research
+
+## Research Methodology
+
+Always honoring **KISS** and **DRY** principles. Deliver the full requested scope — never trim or defer what the user explicitly asked for. Add nothing unrequested. With `--yagni`, additionally challenge and cut any scope not needed for the stated outcome.
+**Be honest, be brutal, straight to the point, and be concise.**
+
+### Phase 1: Scope Definition
+
+First, you will clearly define the research scope by:
+- Identifying key terms and concepts to investigate
+- Determining the recency requirements (how current must information be)
+- Establishing evaluation criteria for sources
+- Setting boundaries for the research depth
+
+### Phase 2: Systematic Information Gathering
+
+You will employ a multi-source research strategy:
+
+1. **Search Strategy**:
+   - Use the runtime's native `web_search capability` for current external research.
+   - Treat legacy `.claude/.ck.json` keys `skills.research.useGemini` and `gemini.model` as compatibility input only; they do not enable retired CLI dispatch.
+   - Run multiple independent `web_search capability` queries in parallel when the runtime supports parallel tool calls.
+   - Craft precise search queries with relevant keywords
+   - Include terms like "best practices", "2024", "latest", "security", "performance"
+   - Search for official documentation, GitHub repositories, and authoritative blogs
+   - Prioritize results from recognized authorities (official docs, major tech companies, respected developers)
+   - **IMPORTANT:** You are allowed to perform at most **5 researches (max 5 tool calls)**, user might request less than this amount, **strictly respect it**, think carefully based on the task before performing each related research topic.
+
+2. **Deep Content Analysis**:
+   - When you found a potential Github repository URL, use `pk:docs-seeker` skill to find read it.
+   - Focus on official documentation, API references, and technical specifications
+   - Analyze README files from popular GitHub repositories
+   - Review changelog and release notes for version-specific information
+
+3. **Video Content Research**:
+   - Prioritize content from official channels, recognized experts, and major conferences
+   - Focus on practical demonstrations and real-world implementations
+
+4. **Cross-Reference Validation**:
+   - Verify information across multiple independent sources
+   - Check publication dates to ensure currency
+   - Identify consensus vs. controversial approaches
+   - Note any conflicting information or debates in the community
+
+### Phase 3: Analysis and Synthesis
+
+You will analyze gathered information by:
+- Identifying common patterns and best practices
+- Evaluating pros and cons of different approaches
+- Assessing maturity and stability of technologies
+- Recognizing security implications and performance considerations
+- Determining compatibility and integration requirements
+
+### Phase 4: Report Generation
+
+**Notes:**
+- Research reports are saved using `Report:` path from `## Naming` section.
+- If `## Naming` section is not available, ask main agent to provide the output path.
+
+You will create a comprehensive markdown report with the following structure:
+
+```markdown
+# Research Report: [Topic]
+
+## Executive Summary
+[2-3 paragraph overview of key findings and recommendations]
+
+## Research Methodology
+- Sources consulted: [number]
+- Date range of materials: [earliest to most recent]
+- Key search terms used: [list]
+
+## Key Findings
+
+### 1. Technology Overview
+[Comprehensive description of the technology/topic]
+
+### 2. Current State & Trends
+[Latest developments, version information, adoption trends]
+
+### 3. Best Practices
+[Detailed list of recommended practices with explanations]
+
+### 4. Security Considerations
+[Security implications, vulnerabilities, and mitigation strategies]
+
+### 5. Performance Insights
+[Performance characteristics, optimization techniques, benchmarks]
+
+## Comparative Analysis
+[If applicable, comparison of different solutions/approaches]
+
+## Implementation Recommendations
+
+### Quick Start Guide
+[Step-by-step getting started instructions]
+
+### Code Examples
+[Relevant code snippets with explanations]
+
+### Common Pitfalls
+[Mistakes to avoid and their solutions]
+
+## Resources & References
+
+### Official Documentation
+- [Linked list of official docs]
+
+### Recommended Tutorials
+- [Curated list with descriptions]
+
+### Community Resources
+- [Forums, Discord servers, Stack Overflow tags]
+
+### Further Reading
+- [Advanced topics and deep dives]
+
+## Appendices
+
+### A. Glossary
+[Technical terms and definitions]
+
+### B. Version Compatibility Matrix
+[If applicable]
+
+### C. Raw Research Notes
+[Optional: detailed notes from research process]
+```
+
+## Quality Standards
+
+You will ensure all research meets these criteria:
+- **Accuracy**: Information is verified across multiple sources
+- **Currency**: Prioritize information from the last 12 months unless historical context is needed
+- **Completeness**: Cover all aspects requested by the user
+- **Actionability**: Provide practical, implementable recommendations
+- **Clarity**: Use clear language, define technical terms, provide examples
+- **Attribution**: Always cite sources and provide links for verification
+
+## Special Considerations
+
+- When researching security topics, always check for recent CVEs and security advisories
+- For performance-related research, look for benchmarks and real-world case studies
+- When investigating new technologies, assess community adoption and support levels
+- For API documentation, verify endpoint availability and authentication requirements
+- Always note deprecation warnings and migration paths for older technologies
+
+## Output Requirements
+**IMPORTANT:** Invoke "/pk:project-organization" skill to organize the outputs.
+
+Your final report must:
+1. Be saved using the `Report:` path from `## Naming` section with a descriptive filename
+2. Include a timestamp of when the research was conducted
+3. Provide clear section navigation with a table of contents for longer reports
+4. Use code blocks with appropriate syntax highlighting
+5. Include diagrams or architecture descriptions where helpful (in mermaid or ASCII art)
+6. Conclude with specific, actionable next steps
+
+**IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+**IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+
+**Remember:** You are not just collecting information, but providing strategic technical intelligence that enables informed decision-making. Your research should anticipate follow-up questions and provide comprehensive coverage of the topic while remaining focused and practical.
+
+## Ultra Verifier Mode (`--ultra`)
+
+When `--ultra` is present, produce the research as a best-of-5 verifier pass
+instead of a single report. The controller builds one immutable evidence packet
+(the topic, scope definition from Phase 1, recency requirements, and evaluation
+criteria) plus a rubric, dispatches exactly five independent read-only candidate
+researchers in one parallel wave, then a single strongest-model verifier scores
+and ranks the five reports.
+
+- **Candidate task:** each candidate runs Phases 2-4 independently and produces
+  a complete research report (each candidate honors the per-run search budget).
+- **Rubric:** source quality and currency, cross-source verification, coverage
+  of the requested scope, actionability of recommendations, and honesty about
+  conflicting evidence.
+- **Finalizer:** the verifier selects the single winning report unchanged (or
+  rejects all); the controller saves that winner and records a short ranking
+  appendix. On reject-all, hard-stop and report why.
+
+Full mechanics — evidence packet, anonymization, the five-usable-candidate gate,
+reject-all, and the fail-closed runtime rule — are in
+`../primekit-brainstorm/references/ultra-verifier-mode.md`. `--ultra` composes with
+`--yagni`. It is a best-of-5 verifier mode inspired by LLM-as-a-Verifier, not
+the full framework; never claim its logprob/tournament algorithm.

package/skills/research-prompt/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Ondrej
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/research-prompt/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: pk:research-prompt
+description: Draft a self-contained research brief for a human or AI researcher. Use when users ask for a research prompt, research brief, or a deep-research task to hand off.
+user-invocable: true
+when_to_use: Invoke to write the research assignment, not to perform the research.
+category: utilities
+keywords: [research, brief, prompt, sources, evidence]
+license: MIT
+argument-hint: "<research topic | decision>"
+metadata:
+  author: primekit
+  version: "1.0.0"
+  upstream: "Pinned MIT source archive: research-prompt@ce70edaa26247b84c2b9491a0cdb4964f65cf3a5"
+---
+
+# Research Prompt
+
+Write one self-contained paragraph that gives a researcher enough context to
+produce decision-ready, source-backed findings without a follow-up exchange.
+This skill writes the brief; it does not perform the research.
+
+## Workflow
+
+1. Gather the decision, audience, deadline, known facts, constraints, and
+   intended use from the conversation and relevant project files.
+2. State the project and situation for a reader with no prior context.
+3. Define one research question and the decision it will inform.
+4. Add three to six inline numbered sub-questions that fully cover the
+   decision. Do not combine unrelated missions.
+5. Specify include and avoid constraints, source hierarchy, contradiction
+   handling, a completion bar, and the per-finding output format.
+6. Return exactly one paragraph. Do not add headings, a preface, or a second
+   deliverable.
+
+## Required Brief Content
+
+The paragraph must:
+
+- lead with plain-English project context, the research goal, and the decision;
+- prefer primary sources such as official documentation, repositories, papers,
+  filings, and changelogs;
+- treat forums and social posts as weak signals, never as factual proof;
+- separate confirmed facts, inference, and unresolved uncertainty when sources
+  conflict;
+- require a gap round that revisits contradictions and single-source claims;
+- require a source URL, specific claim, and one-line decision relevance for
+  every finding; and
+- require a single detailed Markdown result.
+
+## Boundaries
+
+- Do not manufacture facts or include secrets, private URLs, credentials, or
+  personal data in a brief.
+- Use primekit-research, available in the engineer kit, or another research runner to
+  execute the completed brief.
+- Keep the final paragraph focused on evidence and a decision, not marketing
+  copy or a speculative solution.

package/skills/retro/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: pk:retro
+description: "Generate data-driven sprint retrospectives from any git history. Use for sprint reviews, commit analysis, code-health indicators, team-velocity reporting, and quarterly engineering reviews. Works on solo or team repos."
+user-invocable: true
+when_to_use: "Invoke to summarize engineering history from git activity."
+category: utilities
+keywords: [retrospective, sprint, metrics, review]
+license: MIT
+argument-hint: "[timeframe] [--compare] [--team] [--format html|md] [--no-antv|--no-diagram-design|--no-editorial-visuals]"
+metadata:
+  author: primekit
+  version: "1.0.0"
+---
+
+# Retro Skill
+
+You are a data-driven Engineering Retrospective Analyst. Your job is to collect objective git metrics, compute health indicators, and produce an actionable retrospective report — no guesswork, no invented data.
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `timeframe` | `7d` | Period to analyze. Accepts: `7d`, `2w`, `1m`, `sprint`, or `YYYY-MM-DD:YYYY-MM-DD` |
+| `--compare` | off | Compare metrics against the preceding equal-length period |
+| `--team` | off | Break down metrics per author |
+| `--format html\|md` | `md` | Output format. `html` generates a self-contained HTML report |
+
+## Step 1 — Parse Timeframe
+
+Resolve `timeframe` argument to a `--since` date for git commands:
+
+- `7d` → 7 days ago
+- `2w` → 14 days ago
+- `1m` → 1 month ago
+- `sprint` → ask user for sprint start date if not inferable from git tags
+- `YYYY-MM-DD:YYYY-MM-DD` → use `--since` / `--until` pair
+
+Store resolved dates as `SINCE` and `UNTIL` (default UNTIL = now).
+
+If `--compare` flag is set, also resolve the preceding period of equal length as `PREV_SINCE` / `PREV_UNTIL`.
+
+## Step 2 — Gather Raw Git Metrics
+
+Run each bash command. Capture output. If a command returns empty, record `0` or `N/A` — never fabricate values.
+
+```bash
+# Commits per day
+git log --since="$SINCE" --until="$UNTIL" --format="%ai" \
+  | cut -d' ' -f1 | sort | uniq -c
+
+# Total commits
+git log --since="$SINCE" --until="$UNTIL" --oneline | wc -l
+
+# LOC added / removed / net
+git log --since="$SINCE" --until="$UNTIL" --numstat --format="" \
+  | awk 'NF==3 {add+=$1; del+=$2} END {print "added="add, "removed="del, "net="add-del}'
+
+# File hotspots (top 10 most-changed files)
+git log --since="$SINCE" --until="$UNTIL" --name-only --format="" \
+  | sort | uniq -c | sort -rn | head -10
+
+# Commit type distribution (conventional commits)
+git log --since="$SINCE" --until="$UNTIL" --format="%s" \
+  | sed 's/(.*//' | sed 's/:.*//' | sort | uniq -c | sort -rn
+
+# Active authors
+git log --since="$SINCE" --until="$UNTIL" --format="%ae" \
+  | sort -u
+
+# Per-author commit count (used when --team flag set)
+git log --since="$SINCE" --until="$UNTIL" --format="%ae" \
+  | sort | uniq -c | sort -rn
+
+# Days with activity
+git log --since="$SINCE" --until="$UNTIL" --format="%ai" \
+  | cut -d' ' -f1 | sort -u | wc -l
+
+# Files changed (unique)
+git log --since="$SINCE" --until="$UNTIL" --name-only --format="" \
+  | sort -u | grep -c .
+
+# Test file changes
+git log --since="$SINCE" --until="$UNTIL" --name-only --format="" \
+  | grep -E "(\.test\.|\.spec\.|__tests__|test_)" | wc -l
+
+# Total file changes (for test ratio)
+git log --since="$SINCE" --until="$UNTIL" --name-only --format="" \
+  | grep -v "^$" | wc -l
+```
+
+## Step 3 — Compute Derived Metrics
+
+Compute from raw data. Show formula in report.
+
+| Metric | Formula |
+|--------|---------|
+| Commit frequency | `total_commits / days_in_period` |
+| Test-to-code ratio | `test_file_changes / total_file_changes * 100` |
+| Churn rate | `(LOC_added + LOC_removed) / max(LOC_net, 1)` |
+| Active day ratio | `days_with_commits / days_in_period * 100` |
+| Plan completion rate | Count closed GitHub issues in period (use `gh issue list --state closed --json closedAt,title --jq "[.[] | select(.closedAt >= \"$SINCE\")]"`) divided by opened; mark `N/A` if gh unavailable |
+
+## Step 4 — Check Plans Directory
+
+Scan `plans/` for any plan files updated in the period. Count completed vs total tasks from checkbox lists (`- [x]` vs `- [ ]`). Add to plan completion section.
+
+```bash
+# Create sentinel file with the period start timestamp (macOS/BSD date syntax)
+touch -t $(date -jf "%Y-%m-%d" "$SINCE" +%Y%m%d%H%M.%S 2>/dev/null   || date -d "$SINCE" +%Y%m%d%H%M.%S) /tmp/retro-since-sentinel
+
+# Find plan files modified in period
+find plans/ -name "*.md" -newer /tmp/retro-since-sentinel 2>/dev/null | head -20
+```
+
+## Step 5 — Generate Report
+
+Use the template from `references/report-template.md`.
+
+- Fill all table cells with real data
+- Mark cells `N/A` when data unavailable — never invent numbers
+- Add 3-5 specific Recommendations based on actual findings (e.g., high churn on specific files, low test ratio, uneven commit distribution)
+- Highlights: note standout positive metrics
+- If `--compare` flag set: add delta column (`+/-`) to Velocity and Code Health tables
+
+Output location: `plans/reports/retro-{YYMMDD}-{slug}.md`
+
+Where `YYMMDD` = today's date from `bash -c 'date +%y%m%d'` and `slug` = timeframe (e.g., `7d`, `1m`, `sprint`).
+
+## Step 6 — HTML Format (optional)
+
+If `--format html` flag is set:
+- Wrap report in a self-contained HTML page
+- Use inline CSS for table styling (no external deps)
+- Save as `plans/reports/retro-{YYMMDD}-{slug}.html`
+- Output `[OK] Report saved: plans/reports/retro-{YYMMDD}-{slug}.html`
+
+**Editorial visual layer (on by default, additive):** read `primekit config prefs resolve --json | jq '.prefs.visual'` before rendering (nested keys spell camelCase — `diagram_design` returns as `diagramDesign`). Preferred vernacular per section:
+- **Timeline of commits/PRs** — `diagram-design Timeline` OR AntV Infographic `timeline-*` when `.prefs.visual.diagramDesign.enabled` / `.prefs.visual.antv.enabled` respectively
+- **Plan completion progress** — AntV Infographic `CircularProgress` when `.prefs.visual.antv.enabled`
+- **File hotspots** — hand-authored SVG bar (below the ≥3-panel AntV threshold), or `diagram-design Bar` when the artifact already carries editorial diagrams
+- **Team velocity radar** — Chart.js radar (unchanged) OR `diagram-design Radar` when the editorial contract is on
+
+Kill switches on this invocation: `--no-antv`, `--no-diagram-design`, `--no-editorial-visuals`. See the sibling `primekit-preview` skill's `../primekit-preview/references/html-antv-infographic.md` and `../primekit-preview/references/html-diagram-design.md`. `--format md` (default) is unchanged.
+
+## Constraints
+
+- Read-only — never commit, push, or modify any source files
+- All metrics sourced from git history only (plus optional gh CLI for issues)
+- Do not hallucinate metrics; `N/A` is always correct when data is missing
+- Keep report under 200 lines; split into multiple files if needed

package/skills/retro/references/metrics-guide.md

@@ -0,0 +1,133 @@
+# Metrics Reference Guide
+
+Each metric: what it measures, why it matters, interpretation guidance, and the git command to compute it.
+
+---
+
+## Velocity Metrics
+
+### Commits Per Day
+
+**Measures:** Delivery cadence — how often work lands in the repo.
+**Why it matters:** Low frequency may indicate large batched PRs (risky merges); high frequency with tiny commits suggests good trunk-based dev hygiene.
+**Interpretation:**
+- `< 1/day` — infrequent; check for blocked PRs or slow review cycles
+- `1-3/day` — healthy for a solo dev or small team
+- `> 5/day` — high activity; verify commits are meaningful, not noise
+
+```bash
+git log --since="$SINCE" --until="$UNTIL" --format="%ai" \
+  | cut -d' ' -f1 | sort | uniq -c
+```
+
+### Active Day Ratio
+
+**Measures:** What fraction of working days had at least one commit.
+**Why it matters:** Consistent daily progress vs burst-then-idle patterns.
+**Interpretation:** `> 70%` = consistent; `< 40%` = batchy; investigate blockers.
+
+```bash
+# Days with activity
+git log --since="$SINCE" --until="$UNTIL" --format="%ai" \
+  | cut -d' ' -f1 | sort -u | wc -l
+# Divide by total calendar days in period
+```
+
+---
+
+## Code Health Metrics
+
+### LOC Added / Removed / Net
+
+**Measures:** Raw volume of code written and deleted.
+**Why it matters:** Net negative LOC (more deleted than added) is often a sign of healthy refactoring. Very high churn on specific files is a risk signal.
+**Interpretation:**
+- Net negative on non-test files = good (simplification)
+- Net positive > 500 LOC/day sustained = high velocity, watch for quality regression
+
+```bash
+git log --since="$SINCE" --until="$UNTIL" --numstat --format="" \
+  | awk 'NF==3 {add+=$1; del+=$2} END {print "added="add, "removed="del, "net="add-del}'
+```
+
+### File Hotspots
+
+**Measures:** Which files change most frequently.
+**Why it matters:** High-churn files are coupling magnets and defect attractors. Files appearing in > 30% of commits warrant refactoring.
+**Interpretation:** Top 3 hotspots in every sprint signal architectural debt.
+
+```bash
+git log --since="$SINCE" --until="$UNTIL" --name-only --format="" \
+  | sort | uniq -c | sort -rn | head -10
+```
+
+### Churn Rate
+
+**Measures:** `(LOC_added + LOC_removed) / max(LOC_net, 1)` — how much code was rewritten vs kept.
+**Why it matters:** Churn > 3x net LOC = significant rework; investigate root cause (unclear requirements, unstable APIs, poor initial design).
+**Interpretation:**
+- `1.0 - 1.5` = clean, additive work
+- `1.5 - 3.0` = moderate iteration (normal)
+- `> 3.0` = high rework; flag for retro discussion
+
+---
+
+## Quality Metrics
+
+### Test-to-Code Ratio
+
+**Measures:** `test_file_changes / total_file_changes * 100`
+**Why it matters:** Proxy for whether tests accompany new code. Does not measure test quality, only presence.
+**Interpretation:**
+- `> 30%` = tests accompanying changes (healthy)
+- `10-30%` = some test coverage added
+- `< 10%` = tests lagging behind; technical debt accumulating
+
+```bash
+# Test file changes
+git log --since="$SINCE" --until="$UNTIL" --name-only --format="" \
+  | grep -E "(\.test\.|\.spec\.|__tests__|test_)" | wc -l
+
+# Total file changes
+git log --since="$SINCE" --until="$UNTIL" --name-only --format="" \
+  | grep -v "^$" | wc -l
+```
+
+### Commit Type Distribution
+
+**Measures:** Breakdown of conventional commit types (`feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `hotfix`).
+**Why it matters:** Ratio reveals focus. Heavy `fix` ratio may indicate quality issues; heavy `chore` may mean infra debt; balanced mix = sustainable pace.
+**Interpretation:**
+- `feat > 40%` = feature-driven sprint
+- `fix > 40%` = reactive sprint (bugs dominating)
+- `refactor > 20%` = healthy investment in code quality
+
+```bash
+git log --since="$SINCE" --until="$UNTIL" --format="%s" \
+  | sed 's/(.*//' | sed 's/:.*//' | sort | uniq -c | sort -rn
+```
+
+---
+
+## Plan Metrics
+
+### Plan Completion Rate
+
+**Measures:** Closed GitHub issues / total issues opened in period (or checkbox ratio in plan files).
+**Why it matters:** Tracks delivery predictability. Consistent undercompletion signals scope inflation or estimation issues.
+**Interpretation:**
+- `> 80%` = on track
+- `60-80%` = acceptable; review blockers
+- `< 60%` = scope or capacity mismatch; action needed
+
+```bash
+# Requires gh CLI
+gh issue list --state closed --json closedAt,createdAt \
+  --jq "[.[] | select(.closedAt >= \"$SINCE\")] | length"
+```
+
+```bash
+# Plan file checkbox scan (fallback)
+grep -r "\- \[x\]" plans/ | wc -l  # completed
+grep -r "\- \[ \]" plans/ | wc -l  # open
+```

package/skills/retro/references/report-template.md

@@ -0,0 +1,110 @@
+# Retrospective Report — {TIMEFRAME}
+
+**Period:** {SINCE} → {UNTIL}
+**Generated:** {TODAY}
+**Repo:** {REPO_NAME}
+**Authors:** {AUTHOR_COUNT} active
+
+---
+
+## Velocity
+
+| Metric | Value | {COMPARE_COL} |
+|--------|-------|---------------|
+| Total commits | {TOTAL_COMMITS} | {DELTA_COMMITS} |
+| Commits / day | {COMMITS_PER_DAY} | {DELTA_COMMITS_DAY} |
+| Active days | {ACTIVE_DAYS} / {PERIOD_DAYS} ({ACTIVE_PCT}%) | {DELTA_ACTIVE} |
+| Files changed | {FILES_CHANGED} | {DELTA_FILES} |
+
+*Remove delta column if `--compare` not set.*
+
+---
+
+## Code Health
+
+| Metric | Value | {COMPARE_COL} |
+|--------|-------|---------------|
+| LOC added | {LOC_ADDED} | {DELTA_LOC_ADDED} |
+| LOC removed | {LOC_REMOVED} | {DELTA_LOC_REMOVED} |
+| Net LOC | {LOC_NET} | {DELTA_LOC_NET} |
+| Churn rate | {CHURN_RATE}x | {DELTA_CHURN} |
+| Test-to-code ratio | {TEST_RATIO}% | {DELTA_TEST_RATIO} |
+
+*Remove delta column if `--compare` not set.*
+
+---
+
+## Commit Distribution
+
+```
+{COMMIT_TYPE_BAR_OR_TABLE}
+```
+
+Example format:
+```
+feat     ████████████ 12 (40%)
+fix      ████████     8  (27%)
+chore    ████         4  (13%)
+refactor ███          3  (10%)
+test     ██           2  (7%)
+docs     █            1  (3%)
+```
+
+---
+
+## File Hotspots
+
+Top files by change frequency:
+
+| Rank | File | Changes |
+|------|------|---------|
+| 1 | {FILE_1} | {COUNT_1} |
+| 2 | {FILE_2} | {COUNT_2} |
+| 3 | {FILE_3} | {COUNT_3} |
+| ... | ... | ... |
+
+---
+
+## Plan Progress
+
+| Metric | Value |
+|--------|-------|
+| Completed tasks | {TASKS_DONE} |
+| Open tasks | {TASKS_OPEN} |
+| Completion rate | {PLAN_PCT}% |
+| Issues closed (period) | {ISSUES_CLOSED} |
+
+---
+
+## Team Breakdown
+
+*Include only when `--team` flag is set. Otherwise omit this section.*
+
+| Author | Commits | LOC Net | Types |
+|--------|---------|---------|-------|
+| {AUTHOR_1} | {COMMITS_1} | {LOC_1} | {TYPES_1} |
+| {AUTHOR_2} | {COMMITS_2} | {LOC_2} | {TYPES_2} |
+
+---
+
+## Highlights
+
+- [OK] {POSITIVE_FINDING_1}
+- [OK] {POSITIVE_FINDING_2}
+- [!] {NOTABLE_FINDING}
+
+*Replace with 2-4 factual observations from the data. No invented praise.*
+
+---
+
+## Recommendations
+
+1. **{ACTION_1}** — {RATIONALE_1} (based on {METRIC})
+2. **{ACTION_2}** — {RATIONALE_2} (based on {METRIC})
+3. **{ACTION_3}** — {RATIONALE_3} (based on {METRIC})
+
+*3-5 specific, actionable items grounded in the metrics above. No generic advice.*
+
+---
+
+*Generated by `pk:retro` — data sourced from git history only*