<quick_start> Capture today's metrics:
# Quick session stats
echo "Commits: $(git log --since='today 00:00' --oneline | wc -l | tr -d ' ')"
echo "Files changed: $(git diff --stat $(git log --since='today 00:00' --format='%H' | tail -1)..HEAD 2>/dev/null | tail -1)"
Generate weekly report:
cat ~/.claude/portfolio/daily-metrics.jsonl | jq -s 'map(select(.date >= "'$(date -v-7d +%Y-%m-%d)'"))'
Deliverable (the "artifact" in the name): the weekly digest / executive summary / sprint report is rendered as a single-file HTML page at ~/.claude/portfolio/weekly-YYYY-WW.html (or exec-YYYY-WW.html, sprint-<name>.html) and published with the Artifact tool so Tim gets a shareable link; the Markdown templates below are the content model, not the deliverable. Rows whose source data was missing render with a visible "data missing" badge, never as $0 / 0.
</quick_start>
<success_criteria>
- Daily metrics captured automatically via End Day protocol (commits, features, fixes, cost)
- Derived metrics calculated: cost-per-feature, cost-per-bug-fix, lines-per-dollar
- Weekly digest generated with project breakdown and day-by-day trends
- Executive summary ready for stakeholder review with week-over-week comparisons
- Metrics stored persistently at
~/.claude/portfolio/daily-metrics.jsonl - Report rendered as an HTML Artifact (file under
~/.claude/portfolio/+ published link), not only Markdown - Missing inputs (no
daily-cost.json, git/gh unavailable) recorded as explicit*_missingflags, never silently as 0 - Outcome sidecar + run-log line written </success_criteria>
Metrics Captured
Per Session (End Day auto-capture)
| Metric | Source | How |
|---|---|---|
| Commits | git log --since="today" |
Count |
| Files changed | git diff --stat |
Count from diff |
| Lines added/removed | git diff --stat |
Parse +/- |
| Tests added | git diff --stat -- '*.test.*' |
Count test files |
| PRs created | gh pr list --author @me |
GitHub CLI |
| Bugs fixed | Commits matching fix: |
Conventional commits |
| Features shipped | Commits matching feat: |
Conventional commits |
| Cost | ~/.claude/daily-cost.json |
Daily spend |
Derived Metrics
| Metric | Formula | Why It Matters |
|---|---|---|
| Cost per feature | Total cost / feat: commits | Efficiency |
| Cost per bug fix | Total cost / fix: commits | ROI on debugging |
| Lines per dollar | Lines shipped / total cost | Productivity |
| Test coverage delta | Tests added / files changed | Quality signal |
Collection
Automatic (End Day Protocol)
The workflow-orchestrator End Day protocol calls this automatically:
#!/bin/bash
# Auto-capture at end of day — missing inputs are FLAGGED, never defaulted to 0
DATE=$(date +%Y-%m-%d)
FLAGS=()
if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
COMMITS=$(git log --since="today 00:00" --oneline | wc -l | tr -d ' ')
FEATS=$(git log --since="today 00:00" --oneline --grep="^feat" | wc -l | tr -d ' ')
FIXES=$(git log --since="today 00:00" --oneline --grep="^fix" | wc -l | tr -d ' ')
else
COMMITS=null; FEATS=null; FIXES=null; FLAGS+=("git_data_missing")
fi
if [[ -s ~/.claude/daily-cost.json ]] && COST=$(jq -e '.spent' ~/.claude/daily-cost.json 2>/dev/null); then
:
else
COST=null; FLAGS+=("cost_data_missing")
fi
FLAGS_JSON=$(printf '%s\n' "${FLAGS[@]}" | jq -R . | jq -s -c .)
STATUS=$([[ ${#FLAGS[@]} -eq 0 ]] && echo success || echo partial)
mkdir -p ~/.claude/portfolio
echo "{\"date\":\"$DATE\",\"commits\":$COMMITS,\"features\":$FEATS,\"fixes\":$FIXES,\"cost\":$COST,\"flags\":$FLAGS_JSON,\"status\":\"$STATUS\"}" >> ~/.claude/portfolio/daily-metrics.jsonl
A null with a flag is the honest value: the report renders it as "n/a — cost data missing" and excludes the day from cost-per-feature averages. A $0 day is only ever written when daily-cost.json really says 0.
Manual (On-Demand)
# Full session capture with git stats (same flag rule: no commits today ≠ git unavailable)
FIRST=$(git log --since="today 00:00" --format="%H" | tail -1)
if [[ -z "$FIRST" ]]; then
echo "Today: no commits yet"; ADDED=0; REMOVED=0
else
STAT=$(git diff --stat "$FIRST"^..HEAD | tail -1)
ADDED=$(echo "$STAT" | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo 0)
REMOVED=$(echo "$STAT" | grep -oE '[0-9]+ deletion' | grep -oE '[0-9]+' || echo 0)
echo "Today: +$ADDED/-$REMOVED lines, $COMMITS commits ($FEATS features, $FIXES fixes)"
fi
Report Templates
Content model for the HTML Artifact. Build the page from these sections (one <section> per heading, a <table> per table, a data-missing badge wherever the JSONL row carried a flag), save it under ~/.claude/portfolio/, then publish it with the Artifact tool and return the link. Full HTML scaffold and styling notes: reference/report-templates.md.
Executive Summary (C-Suite)
## Engineering Impact — Week of [DATE]
**Headline:** Shipped [N] features, fixed [N] bugs across [N] projects
| Metric | This Week | Last Week | Trend |
|--------|-----------|-----------|-------|
| Features shipped | 5 | 3 | ↑ 67% |
| Bugs fixed | 8 | 12 | ↓ 33% |
| Lines shipped | 1,247 | 890 | ↑ 40% |
| Cost | $12.40 | $15.20 | ↓ 18% |
| Cost/feature | $2.48 | $5.07 | ↓ 51% |
**Key Deliverables:**
- [Feature 1]: [Impact]
- [Feature 2]: [Impact]
**Cost Optimization:** Shifted [N] tasks to Haiku, saving $[X] (Y% reduction)
Weekly Digest
## Weekly Digest — [DATE RANGE]
### By Project
| Project | Commits | Features | Fixes | Cost |
|---------|---------|----------|-------|------|
| skills-library | 12 | 5 | 2 | $3.40 |
| netzero-bot | 8 | 2 | 4 | $5.20 |
### By Day
| Day | Commits | Lines | Cost |
|-----|---------|-------|------|
| Mon | 5 | +234/-45 | $1.80 |
| Tue | 8 | +567/-123 | $2.40 |
| ... | ... | ... | ... |
### Insights
- Most productive day: Tuesday (567 lines)
- Most expensive feature: [feature] ($X)
- Cheapest bug fix: [fix] ($0.12, Haiku)
Sprint Report
## Sprint Report — [SPRINT NAME]
**Duration:** [START] → [END]
**Total Cost:** $[X]
### Deliverables
- [ ] Feature A (shipped, $X)
- [ ] Feature B (shipped, $X)
- [ ] Bug fix C (shipped, $X)
### Velocity
- Story points completed: [N]
- Cost per story point: $[X]
- Average cycle time: [N] hours
Storage
~/.claude/portfolio/
├── daily-metrics.jsonl # One JSON line per day (nulls + flags for missing sources)
├── weekly-YYYY-WW.html # Weekly digest — the published Artifact
├── exec-YYYY-WW.html # Executive summary — the published Artifact
└── sprint-<name>.html # Sprint report — the published Artifact
Integration
| System | Integration |
|---|---|
| workflow-orchestrator | End Day auto-captures daily metrics |
| cost-metering | Provides cost data for cost-per-feature |
| git-workflow | Conventional commits enable feat/fix counting |
| agent-teams | Tracks multi-agent session costs |
Deep dive: See reference/metrics-guide.md, reference/report-templates.md
<self_healing>
Failure = no metric row and no report; partial = a source was missing (git not a repo, gh unauthenticated, daily-cost.json absent) — the row is still written with null + a flag and the report shows a "data missing" badge. Ladder: retry the command once → degrade with the flag → tell Tim in the report header which days are incomplete (no Slack needed; internal skill) → halt only if ~/.claude/portfolio/ is unwritable. Append one line per run to ~/.claude/skill-runs/portfolio-artifact-skill.jsonl. Full contract: ~/.claude/skills/epiphan-house-rules-skill/reference/self-healing.md.
</self_healing>
Emit Outcome Sidecar
As the final step, write to ~/.claude/skill-analytics/last-outcome-portfolio-artifact-skill.json:
{"ts":"[UTC ISO8601]","skill":"portfolio-artifact-skill","version":"<frontmatter version>","variant":"default",
"status":"[success|partial|error]","runtime_ms":[estimated ms from start],
"metrics":{"metrics_captured":[n],"artifacts_generated":[n],"reports_created":[n],"days_with_missing_data":[n]},
"error":null,"session_id":"[YYYY-MM-DD]"}
Use status "partial" if some stages failed but results were produced (name the stage in error, e.g. cost_data_missing). Use "error" only if no output was generated.