serejaris/ris-claude-code/weekly-retro

Weekly Retro

Part of the Personal Corp framework — running a one-person business through AI agents.

Structured weekly retrospective. Gather facts from code and project management tools, interview the founder, capture findings into issues and canonical files.

Setup

Before first use, define these in your project's CLAUDE.md:

## Weekly Retro Config
 
### Repos to scan
List all repos the agent should check for commits:
-~/Projects/main-app
-~/Projects/marketing-site
-~/Projects/docs
 
### GitHub owner
Your GitHub username or org for issue search:
-owner: your-github-handle
 
### GitHub Project ID
Project board where retro issues land:
-project_id: 7
 
### Canonical files (single source of truth)
Files that hold authoritative data — agent must check these before writing numbers:
-data.md — prices, revenue, historical totals
-product.md — current offers
-insights.md — strategic conclusions
 
### Retro log path
Where retro artifacts are saved. Two files per retro live here:
-`WNN.md` — interview log + final summary
-`WNN-outcomes.md` — outcomes scorecard (planned outcomes vs evidence)
 
Example:
-retro_log_path: docs/retro/
 
### Task routing
Map task types to repos so issues land in the right place:
| Type | Repo |
|------|------|
| Backend bugs | main-app |
| Marketing | marketing-site |
| Strategy, cross-cutting | project-brain |
 
### Interview topics (customize to your business)
Ordered list of areas to cover:
1.Product delivery
2.Sales / pipeline
3.Calendar events
4.New initiatives
5.Research / strategy
6.Open question
 
### Work Areas (customize names, goals, and colors)
Each Area is a stable responsibility lens used by retro, planning, and the living weekly page:
1.Delivery
2.Sales
3.Systems
4.Content
5.People
6.Strategy
7.Wealth (recovery habits such as sport and reflection)

No separate init skill needed — this section is the setup. Copy the config block above into your CLAUDE.md, fill in your values, and the skill is ready.

Two modes — never mix

Retro = looking back. Planning = looking forward. Finish the retro completely, output the backlog, THEN plan.

If the founder wants to switch to planning before retro is done: "OK, N topics still uncovered: [list]. Skip or quick pass? After that — planning." Give the choice, don't switch silently.

Iron Rules

digraph rules {
    rankdir=LR;
    "Calendar event" -> "ASK what it is" [label="don't assume"];
    "Want to create issue" -> "VERIFY: gh + ls + git" [label="first"];
    "Learned a fact" -> "WRITE immediately" [label="canonical/issue"];
    "Want to recommend" -> "Finish gathering facts" [label="not before Phase 4"];
    "Numbers diverge" -> "Show divergence" [label="don't write silently"];
}

1. ASK don't ASSUME — Calendar says "Meeting (Name)"? Does NOT mean you know what it was. Ask.
2. VERIFY before CREATE — Check for duplicates (gh issue list --search) + clarify scope. If fact is NEW and no issue exists — ask the founder: "Is this a task? What exactly should be done, in which repo?" Not every mention = issue.
3. SAVE immediately — Learned a fact? Edit/Write right now. "Noted" without writing = not noted.
4. NO FABRICATION — Don't invent numbers. Not in canonical files or live stats? Don't write it.
5. INTERVIEW FIRST — Data from git/issues is NOT sufficient. The founder knows context that is written nowhere.
6. One question at a time — One topic, answer, write it down, next.
7. CONFLICT RESOLUTION — If the founder states a number different from canonical source, show the divergence: "data.md says 25, you say 30. Which is correct?" Write only after resolution.
8. PHASE DISCIPLINE — Phase 2 (interview) writes ONLY to the retro log file ($RETRO_LOG_PATH/WNN.md). Do NOT create issues, do NOT edit canonical files, do NOT touch CRM/contact cards in Phase 2. All canonical mutations are Phase 6 batch. All new issues are Phase 5 batch after explicit founder approve.
9. OUTCOMES SCORECARD REQUIRED — Before Phase 2, read $RETRO_LOG_PATH/WNN-outcomes.md (written by the planning skill at the start of the week). Fill Status for each outcome via fast subagent (evidence from issues / calendar / canonical files). If the file does not exist — ask founder to reconstruct or skip explicitly, do not silently go into free interview.
10. WEEK ENDS WITH ZERO OPEN WNN ITEMS — The retro is not closed until every open issue labeled with the closing week (retro:WNN or WNN) gets a terminal decision: close / drop / promote (to epic) / spillover (with explicit causal reason). "Leave it hanging" is NOT a terminal decision. See Phase 5.5.
11. NO STALE ROLLOVER — An item cannot spillover for a 3rd consecutive week. If an issue carries retro:W{N-2} + retro:W{N-1} and the founder wants another spillover into W{N+1} → STOP. Reformulate as close / drop / promote-to-epic. A re-label is not allowed.

Numbers trust hierarchy

Phase 1: Gather Data (before interview, automatic)

Step 0 — create the retro log file immediately. Before any data gathering, create $RETRO_LOG_PATH/WNN.md (where NN is the closing week). All subsequent writes during the interview land in this single file — not scattered notes, not memory.

All gathering in parallel:

# 1. Git commits across all repos (use repos from your CLAUDE.md config)
for repo in $YOUR_REPOS; do
  echo "=== $repo ==="
  cd $repo 2>/dev/null && git log --oneline --after="YYYY-MM-DD" --before="YYYY-MM-DD" | head -10
  cd -
done
 
# 2. GitHub issues closed + updated
gh search issues --owner $YOUR_OWNER --updated "YYYY-MM-DD..YYYY-MM-DD" --json repository,number,title,state
 
# 3. Open issues on main project board
gh issue list -R $YOUR_OWNER/$YOUR_MAIN_REPO --state open --json number,title --limit 30
 
# 4. Previous retro carry-over (all open retro:W* labels, not only retro:W{N-1})
gh search issues --owner $YOUR_OWNER --state open --json repository,number,title,labels,createdAt \
  --jq '[.[] | select(.labels[].name | startswith("retro:W")) | {repo: .repository.nameWithOwner, n: .number, title, labels: [.labels[].name | select(startswith("retro:W"))], created: .createdAt}]'

Show summary to the user. Ask for a calendar screenshot (if they don't provide one — work with git/issues, don't insist).

Previous retro carry-over + aging

Group carry-over items by oldest retro:W* label. Column "weeks open" = current_week − min(retro:W labels).

### Carry-over by age
| Issue | Repo | Title | Open for | Labels |
|---|---|---|---|---|
| #157 | main-app | feature X follow-up | 1 week  | retro:W{N-1} |
| #48  | crm      | client Y invoice    | 2 weeks | retro:W{N-2}, retro:W{N-1} |
| #1   | legal    | tax registration    | 4 weeks | retro:W{N-4}…W{N-1} |
 
**Stale-warning:** N issues open 2+ weeks. Phase 5.5 will resolve these to terminal decisions before creating the W{N+1} backlog.

This list feeds directly into Phase 5.5.

Phase 1.5: Outcomes scorecard (planned vs actual) — REQUIRED before Phase 2

Without this phase the retro becomes a free conversation about "what happened" instead of an honest check of "what was promised." Outcomes are the only formal link between planning and retro.

Action

1. Read $RETRO_LOG_PATH/WNN-outcomes.md (written by the planning skill at the start of week NN).

1. If the file does not exist → STOP and tell the founder explicitly: "Outcomes for WNN were not recorded at planning time — retro will run without plan/fact comparison. Reconstruct retroactively from last week's notes, or skip the scorecard?". Do not silently skip.

1. For each outcome row (O1..ON) gather evidence in parallel via fast subagents:

• Issues in the row's Issues column: gh issue view <N> -R <repo> — open/closed + last comment
• Calendar events: query Google Calendar by date
• Artifacts: find / git log --grep / canonical-file inspection
• Communications: relationship-context query (if integration exists)

1. Fill the Status column in the same file:

1. Output to founder as a separate block in Phase 1 summary:

## Outcomes scorecard WNN
 
| ID | Outcome | Status | Evidence | Notes |
|---|---|---|---|---|
| O1 | <outcome>     | done       | <issue#> closed, artifact at <path> | — |
| O2 | <outcome>     | partial    | issue closed but Q&A ran long       | bonus 30 min |
| O5 | <outcome>     | miss       | issue still open, 0 broadcasts sent | — |
| O8 | <outcome>     | spillover  | re-labeled retro:W{N+1}             | overdue 3 weeks |
 
**Summary:** 5 done · 1 partial · 1 miss · 1 spillover · 0 dropped (of 8 outcomes)
**Hit rate:** 62% (5/8 done)

1. Only miss / partial / spillover rows become Phase 2 interview topics — founder explains why. Done rows are already proven by evidence; don't spend founder time relitigating them.

Anti-patterns

• Did not open the outcomes file → Phase 2 turns into free discussion. Founder loses honest plan-vs-fact accountability.
• Filled Status without evidence → "done" set on memory alone, false-positive risk. Every "done" requires an evidence row.
• Skipped Phase 1.5 because "it's obvious" → STOP. If the outcomes file exists, reading and filling Status is not optional.

When outcomes file is missing

Possible causes:

• WNN was the first week using this process (no precedent)
• Founder skipped the planning skill's outcomes-write step
• File was lost / mis-pathed

Action:

1. Tell founder explicitly: "No outcomes recorded for WNN. Options: (a) reconstruct retroactively from the prior week's retro summary + current tasks file, (b) skip scorecard and go into open interview."
2. If (a) — mark the reconstructed file with **Reconstructed:** YYYY-MM-DD (no original plan) in its header. Reconstructed outcomes are baseline only — not as reliable as planned ones (selection bias).
3. Fix the cycle going forward: the planning skill must write the outcomes file at the start of next week.

Phase 2: Interview (core of retro)

digraph interview {
    "Show data" -> "Ask about topic";
    "Ask about topic" -> "Answer unclear" -> "Clarify" -> "Ask about topic";
    "Ask about topic" -> "Answer clear" -> "WRITE immediately";
    "Ask about topic" -> "Multi-topic answer" -> "Batch save + list back" -> "Continue with most important topic";
    "WRITE immediately" -> "Issue?" [shape=diamond];
    "Issue?" -> "VERIFY then CREATE" [label="yes"];
    "Issue?" -> "Next topic" [label="no"];
    "VERIFY then CREATE" -> "Next topic";
    "Next topic" -> "Ask about topic" [label="more"];
    "Next topic" -> "Phase 3" [label="done"];
}

Multi-topic response protocol

When the answer covers multiple topics: (1) WRITE each fact immediately (batch is OK), (2) list back to founder: "Saved: X, Y, Z — correct?", (3) continue with the most important uncovered topic, (4) return to skipped items from interview order later.

Interview order

Use the topics from your CLAUDE.md config. Default order: