Skip to content

yearly-report.md

Latest commit

 

History

History
185 lines (119 loc) · 8.87 KB

yearly-report.md

File metadata and controls

185 lines (119 loc) · 8.87 KB
Raw

Generate a professional yearly progress report covering achievements, growth, and future vision. Intended for annual performance reviews, skip-manager discussions, and personal tracking.

Instructions

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

Phase 1 — Load Settings and Confirm Period

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 empty or absent, detect via git config --global user.email.
  • repo_paths: list of root paths or specific repo paths to search.
  • output.reports_dir: base directory for saving reports.

Determine the report period. Default: January 1 to December 31 of the prior year. If the user specified a year when invoking (e.g. "for 2025"), use that.

Confirm with the user:

"Yearly report for: [YYYY] ([start_date] to [end_date]). Correct? (Y/n)"

Phase 2 — Repo Discovery

Step A — Discover all repos:

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.

Present the complete list in a numbered table. Ask user to exclude irrelevant repos.

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 per email; combine. Repos with no commits → ask if user wants to include anyway.

Phase 3 — Section Selection

Present candidate sections. User confirms which to include. Default: all selected.

Select sections to include in this yearly report:

  [1]  High-Level Project Achievements                          ← default ON
  [2]  Impacts — Group/Organization Level                      ← default ON
  [3]  Impacts — Science/Research Community                    ← default ON
  [4]  Technical Capability Growth                             ← default ON
  [5]  Responsibility & Leadership Growth                      ← default ON
  [6]  Potential Future Responsibilities                       ← default ON
  [7]  Goals from Last Year: Addressed / Not Addressed         ← default ON if prior report found
  [8]  Interests, Goals & Vision for Next Year                 ← default ON
  [9]  Questions for Skip Manager / Performance Discussion     ← default ON

Enter indices to REMOVE (comma-separated), or type "ok" to keep all defaults:

Phase 4 — Prior Report Input

Prior yearly report: Scan <reports_dir>/yearly/ for a file from the previous year. If found, offer to include it for goal tracking.

Prior sub-period reports (supplemental): Scan <reports_dir>/midyear/, <reports_dir>/quarterly/, and <reports_dir>/monthly/ for files whose dates fall within the current year.

If supplemental reports are found, ask:

"Found [N] mid-year/quarterly/monthly report(s) for [YYYY]: [filenames]. Include them as supplemental context? (Y/n)"

Supplemental reports provide synthesized impact, growth, and goal-tracking context across the year — use them to enrich all sections, especially impacts and personal growth.

If no prior yearly report is found and section [7] is selected, ask the user to provide a path or skip.

Phase 5 — Parallel Git Analysis

For each active repo, run:

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

Analysis focus for yearly reports — portfolio and career level:

At this scope, the analysis is about the arc of your work portfolio across the year and its cumulative significance.

  1. Identify the 3–6 most significant projects or initiatives you contributed to across the year.
  2. For each: what was the starting state at the beginning of the year? What was shipped, decided, or built? What is the state now? What is the significance of this work?
  3. Look for evidence of year-over-year growth in technical complexity, system scale, and impact scope.
  4. Identify projects where you drove major architectural decisions — capture the decision and its rationale: "[What was decided] to [why / what it enables or avoids]."
  5. Look for evidence of growing ownership: projects where you went from contributor to driver, or from follower to leader.
  6. Synthesize into 4–7 initiative-level achievements that represent the year's portfolio.

Phase 6 — Clarifying Questions

Ask about information git cannot provide:

  • Major conferences, workshops, or invited talks attended or given this year
  • Publications published, submitted, or accepted; citations, awards, or recognition
  • Significant collaborations with external organizations or industry
  • Proposal reviews, advisory roles, committee memberships, or editorial positions
  • Mentoring: postdocs, students, peers you guided or sponsored
  • Significant challenges faced this year — how were they resolved? What did you learn?
  • Moments of major technical or professional growth you want to capture
  • Scope expansions or new responsibilities taken on during the year
  • What aspects of the work energized you most? What felt less aligned with your goals?
  • Where do you want to be in one to three years — what does success look like?
  • Open questions or topics for the annual performance discussion with skip manager

Always append:

"Is there anything else significant from this year not captured in the repositories above?"

Phase 7 — Report Generation

Compose the report using selected sections, git analysis, supplemental reports (if included), user answers, and prior yearly report (if provided).

Goal Tracking section (if prior yearly report included and section [7] selected):

For each goal, commitment, or vision from the prior yearly report:

  • ✅ Addressed: [goal] → [concrete achievement with evidence from the year]
  • ⚠️ Partially addressed: [goal] → [what progressed, what didn't, honest assessment]
  • ❌ Not yet addressed: [goal] → [why not + whether to carry forward or retire]

High-Level Project Achievements:

4–6 paragraphs or bullets covering the year's major initiatives. For each: the problem addressed, the decisions made (with rationale), the outcome delivered, and the lasting significance. Write for an audience who knows your field but not your day-to-day work.

Impacts — Group/Organization Level:

Concrete outcomes for your organization: systems in production, users served, team capabilities unlocked, cross-team collaborations that produced lasting results, processes improved.

Impacts — Science/Research Community:

External outputs and recognition: papers, talks, open-source releases, standards contributions, community leadership, collaborations with other institutions and their outcomes.

Technical Capability Growth:

4–5 sentences on new technical domains, increased depth, or expanded system-level thinking developed this year. Frame as: what problems can you now solve that you couldn't a year ago?

Responsibility & Leadership Growth:

4–5 sentences on how your ownership, influence, and decision-making authority expanded this year. Be specific about what you led, drove, or shaped that others depended on.

Potential Future Responsibilities:

3–4 areas where your growth this year positions you for expanded leadership, ownership, or scope in the coming year. Frame as demonstrated readiness + identified opportunity.

Interests, Goals & Vision for Next Year:

4–6 specific goals for the coming year covering: technical growth, project milestones, community impact, and personal/professional development. Make them concrete, achievable, and evaluable at next year-end.

Questions for Manager/Skip Manager / Performance Discussion:

4–7 discussion points for the annual review: career trajectory, growth areas to invest in, organizational direction, resources or support needed, and explicit recognition of contributions you want acknowledged.

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.

Format:

Print the full report to the terminal.

Then ask:

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

If confirmed, save the file. Create the yearly/ subdirectory if it does not exist.