weekly-report.md

Generate a professional weekly progress report by analyzing git history across configured repositories.

Instructions

Follow the phases below in order. Do not skip any phase.

---

Phase 1 — Load Settings

Read ~/.config/reporting/settings.yaml.

If the file does not exist, tell the user: "Settings not found at ~/.config/reporting/settings.yaml. Please run bash install.sh from the reporting repo and edit settings.yaml." Then stop.

Parse from the settings file:

• author.emails: list of git author emails. If the list is empty or the key is absent, run git config --global user.email to detect the email automatically. Use all configured emails to filter commits.
• repo_paths: list of root paths or specific repo paths to search.
• output.reports_dir: base directory for saving reports.
• weekly.date_range: rolling (default) or calendar_week.
• weekly.template: the report template defining section headings.
• weekly.examples: list of example report entries showing expected tone, style, and level of detail.

Determine the date range:

• rolling → from 7 days ago to today (inclusive)
• calendar_week → from last Monday to last Sunday
• If the user specified a period when invoking the command (e.g. "for the week of March 24–30"), use that instead and confirm with the user.

---

Phase 2 — Repo Discovery

Step A — Discover all repos (present first, analyze second):

Recursively walk each path in repo_paths. For each directory:

• If it contains a .git/ subdirectory → it is a git repo, add it to the list.
• If it does not → continue recursing into its subdirectories.

Do not run any git log commands yet.

Present the complete list to the user in a numbered table:

Discovered repositories (all included by default):

  [1]  ~/Repos/project-alpha
  [2]  ~/Repos/sub-group/project-beta
  ...

Enter indices to EXCLUDE (comma-separated, e.g. "2,5"), or type "ok" to include all:

Wait for the user's response before proceeding.

Step B — Filter by author and date:

For each included repo, run:

git -C <repo_path> log --author="<email>" --since="<start_date>" --until="<end_date>" --oneline

Repeat for each configured email and combine results. A repo is "active" if it has at least one matching commit.

Repos with no matching commits → mark as "no activity this period". Ask:

"These repos had no commits from you in this period: [list]. Include them anyway? (y/N)"

Only analyze repos confirmed for inclusion.

---

Phase 3 — Parallel Git Analysis

For each active repo, run:

git -C <repo_path> log --author="<email>" --since="<start_date>" --until="<end_date>" --patch --no-merges

(Repeat for each email; combine and deduplicate by commit hash.)

Commit synthesis — apply these rules in order:

1. Sort commits chronologically (earliest first).
2. Group into clusters: commits belong to the same cluster if they touch overlapping file areas AND the time gap between consecutive commits is ≤4 hours.
3. For each cluster, analyze the combined diff (the net change from first to last commit in the cluster) — what actually changed in the end state?
4. Label each cluster with a concise past-tense outcome sentence describing what was accomplished.
5. For fix sequences ("try X → fix → fix again → final fix"): report only the resolution — "Resolved [issue] by [approach]." Do not list intermediate attempts.
6. For design or architecture changes: look for rationale in the commit body, PR description, or inline code comments. Format as: "[What changed] to [why / what constraint it addresses]." If rationale cannot be inferred from available context, omit the rationale clause rather than guessing.
7. Discard clusters that only touch: tests, docs, config tweaks, dependency version pins — UNLESS they represent significant standalone work (e.g. a major test infrastructure overhaul or a docs milestone).

Content to INCLUDE:

• New systems, features, or integrations shipped or deployed
• Design and architecture changes, paired with a brief rationale when inferable
• Project milestones, performance improvements, or scalability changes
• High-level blockers resolved (the outcome in one sentence, not debug detail)
• Significant collaborations and their outcomes

Content to EXCLUDE:

• Specific bug fix details, error messages, or stack traces
• Small supporting utilities or helper functions added in service of other features
• Repeated attempts at the same fix (synthesize to the outcome only)
• Internal refactors with no user-visible or project-level effect
• Isolated test additions without broader context

Produce 1–5 high-level bullet points per repo.

---

Phase 4 — Clarifying Questions

Parse the section headings from weekly.template.

For each section heading, decide: can this section be fully answered from git history?

• YES (headings like "Technical Work", "Project Progress", "Development"): already covered by Phase 3 — skip.
• NO (headings like "Meetings", "Travel", "Conference", "Service", "Papers", "Talks", "Misc"): generate a short, targeted question asking what the user did in that area this week.

Present only the generated questions to the user — do not hardcode any specific questions. The questions must derive entirely from the template.

Always append this final question:

"Is there anything else relevant to this week's report that isn't captured in the repositories above?"

Wait for the user's answers before proceeding.

---

Phase 5 — Report Generation

Using the synthesized git content, user answers from Phase 4, the weekly.template, and weekly.examples as style and length guides:

Map content to template sections:

• Apply heuristics: match each piece of content to the best-fit section based on repo purpose, content keywords, and section heading semantics.
• If a piece of content clearly belongs to one section: place it there.
• If a piece of content could reasonably belong to multiple sections: choose the most specific fit.
• If mapping is genuinely ambiguous after thorough consideration: ask the user to decide for that item only.

Format the report:

• Follow the template structure exactly — same section numbering, same heading text.
• Use the examples to calibrate tone (professional, concise), sentence length, and level of detail.
• Write one logical group of bullets per repo under the relevant technical section.
• Consolidate all meeting/service/paper content into their respective non-technical sections.
• Each bullet point should be one to two sentences maximum.

Writing style:

• Keep sentences short and direct. One idea per sentence.
• Keep paragraphs short — 2 to 3 sentences maximum, then break.
• Prefer active voice and concrete verbs ("deployed", "resolved", "redesigned") over abstract or passive constructions.
• Use bullet points for lists of 3 or more items rather than embedding them in prose.
• Use bold or sub-headings to separate distinct topics within a section, so the reader can scan.
• Avoid filler phrases ("In order to", "It is worth noting that", "We were able to"). Cut them.
• When in doubt, cut the sentence in half.

Output:

Print the full formatted report to the terminal.

Then ask:

"Save to <reports_dir>/weekly/<YYYY-MM-DD>-weekly.md? (Y/n) Or enter a different path:"

If confirmed (or Enter pressed), save the file. Create the weekly/ subdirectory under reports_dir if it does not already exist. Use the end date of the report period as the filename date.