Back to Details

personal-commit-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Personal Commit Review

个人提交回顾

Write a short Markdown retrospective of a person's GitHub work. Make it read like a written review, not a changelog and not a bullet-only summary.
撰写一份关于某人GitHub工作的简短Markdown回顾。使其读起来像一份书面报告，而非变更日志或纯要点式总结。

Default Behavior

默认行为

  • If the user does not specify a time period, default to the last 7 days and say so plainly.
  • Default deliverable: one Markdown note, about one page total, usually 400-700 words.
  • Use scripts only when they materially help. This skill is primarily a workflow for gathering evidence and writing well.
  • 如果用户未指定时间段，默认使用过去7天，并明确说明这一点。
  • 默认交付成果：一份Markdown笔记，总篇幅约一页，通常为400-700字。
  • 仅在脚本能切实提供帮助时使用。本技能主要是用于收集证据和撰写优质内容的工作流。

Workflow

工作流程

1. Set the review window

1. 设置审查时间窗口

  • If the period is ambiguous, ask once. If asking would only slow down an otherwise straightforward request, default to the last 7 days and state the assumption.
  • Prefer exact 
    --since
    and 
    --until
    dates for weekly, monthly, quarterly, or release reviews.
  • Decide whether the user wants the review only in chat or also written to a Markdown file.
  • 如果时间段不明确，询问一次。如果询问会拖慢原本简单直接的请求，则默认使用过去7天，并说明这一假设。
  • 对于每周、每月、每季度或版本发布审查，优先使用精确的
    --since
    和
    --until
    日期。
  • 确定用户是仅希望在聊天中查看审查内容，还是同时需要写入Markdown文件。

2. Gather the contribution map

2. 收集贡献图谱

  • Start with GitHub totals and the touched repositories. This gives the frame of the review before you study individual commits.
  • Manual 
    gh
    usage is fine for v1 and should be the default for small review windows or a small number of repos.
  • Use the helper script only when the time window or repo count makes manual collection annoying.
bash
gh api graphql -f query='query {
  viewer {
    login
    contributionsCollection(from:"2026-03-01T00:00:00Z", to:"2026-03-07T23:59:59Z") {
      totalCommitContributions
      restrictedContributionsCount
      commitContributionsByRepository(maxRepositories:25) {
        repository {
          nameWithOwner
          description
          isPrivate
          url
          primaryLanguage { name }
        }
        contributions(first:7) {
          nodes { occurredAt commitCount }
        }
      }
    }
  }
}'
  • If you want the helper path, use:
bash
uv run .agents/skills/personal-commit-review/scripts/collect_commit_review.py \
  --since 2026-03-01 \
  --until 2026-03-07 \
  --output /tmp/commit-review.json \
  --brief-out /tmp/commit-review-brief.md
  • Treat GitHub's contribution totals as authoritative counts and the retrieved commit objects as the visible research set.
  • Open github-collection-notes.md when the data looks incomplete or the GitHub queries need adjustment.
  • 从GitHub总数据和涉及的仓库开始。这能在研究单个提交前为审查构建框架。
  • 对于v1版本，手动使用
    gh
    即可，且在审查窗口较小或仓库数量不多时应作为默认方式。
  • 仅当时间窗口或仓库数量导致手动收集过于繁琐时，才使用辅助脚本。
bash
gh api graphql -f query='query {
  viewer {
    login
    contributionsCollection(from:"2026-03-01T00:00:00Z", to:"2026-03-07T23:59:59Z") {
      totalCommitContributions
      restrictedContributionsCount
      commitContributionsByRepository(maxRepositories:25) {
        repository {
          nameWithOwner
          description
          isPrivate
          url
          primaryLanguage { name }
        }
        contributions(first:7) {
          nodes { occurredAt commitCount }
        }
      }
    }
  }
}'
  • 如果选择辅助脚本路径，使用：
bash
uv run .agents/skills/personal-commit-review/scripts/collect_commit_review.py \
  --since 2026-03-01 \
  --until 2026-03-07 \
  --output /tmp/commit-review.json \
  --brief-out /tmp/commit-review-brief.md
  • 将GitHub的贡献总数视为权威统计，将获取到的提交对象视为可见的研究数据集。
  • 当数据看起来不完整或需要调整GitHub查询时，打开github-collection-notes.md。

3. Understand the repos before interpreting the commits

3. 在解读提交前先了解仓库

  • Do not infer meaning from commit messages alone.
  • For each repo that looks important, gather the minimum context needed to understand what the work was for:
    • repo description and primary language
    • README, architecture note, or docs if the repo has them
    • touched file paths and folder names
    • one or two neighboring commits if a headline is too vague
  • Prefer understanding the product or subsystem before writing about what changed in it.
Useful commands:
bash
gh repo view OWNER/REPO --json nameWithOwner,description,primaryLanguage,url
gh api --method GET repos/OWNER/REPO/commits -f author=USERNAME -f since=2026-03-01T00:00:00Z -f until=2026-03-07T23:59:59Z -f per_page=20
gh api --method GET repos/OWNER/REPO/commits/SHA
  • Example: if a commit mentions Liquid Glass, verify whether the repo is a macOS app, which window or settings files changed, and whether the repo context supports that description.
  • If the repo context is still unclear, describe the change more conservatively.
  • 不要仅从提交消息推断含义。
  • 对于每个重要的仓库，收集理解工作内容所需的最低限度上下文：
    • 仓库描述和主要编程语言
    • 如果仓库有README、架构说明或文档，查看这些内容
    • 涉及的文件路径和文件夹名称
    • 如果提交标题过于模糊，查看一两个相邻的提交
  • 在撰写仓库变更内容前，优先理解产品或子系统的用途。
实用命令：
bash
gh repo view OWNER/REPO --json nameWithOwner,description,primaryLanguage,url
gh api --method GET repos/OWNER/REPO/commits -f author=USERNAME -f since=2026-03-01T00:00:00Z -f until=2026-03-07T23:59:59Z -f per_page=20
gh api --method GET repos/OWNER/REPO/commits/SHA
  • 示例：如果某提交提到Liquid Glass，验证该仓库是否为macOS应用、哪些窗口或设置文件发生了变更，以及仓库上下文是否支持该描述。
  • 如果仓库上下文仍不明确，更保守地描述变更内容。

4. Pick the storylines

4. 选定叙事主线

  • Pick 2-4 themes for the review, not 10 separate commit bullets.
  • Good themes are usually product-facing or architectural:
    • interface polish and design alignment
    • release and packaging work
    • infrastructure or tooling improvements
    • a feature thread that moved from idea to working implementation
  • Support each theme with concrete evidence from commits, repo context, and changed paths.
  • 为审查选择2-4个主题，而非10个独立的提交要点。
  • 优质主题通常面向产品或架构：
    • 界面优化与设计对齐
    • 版本发布与打包工作
    • 基础设施或工具改进
    • 从想法到可运行实现的功能迭代
  • 用来自提交、仓库上下文和变更路径的具体证据支撑每个主题。

5. Parallelize research when it actually helps

5. 在切实有帮助时并行开展研究

  • If the review spans many repos or many strong highlights, split follow-up work by repo or theme.
  • Give each subagent exclusive ownership of specific repos or highlight commits.
  • Do not have every subagent repeat the full discovery step.
  • Keep the main agent responsible for the final narrative voice and the final fact check.
  • 如果审查涉及多个仓库或多个重要亮点，按仓库或主题拆分后续工作。
  • 让每个子Agent专门负责特定仓库或重点提交。
  • 不要让每个子Agent重复完整的发现步骤。
  • 由主Agent负责最终叙事风格和最终事实核查。

6. Write the review as prose

6. 以散文形式撰写审查报告

  • Use the default structure in output-template.md.
  • Do not return a wall of paragraphs. The final Markdown should read like a compact report.
  • Start with a short framing paragraph that includes the key stats: commit count, repo count, major languages, and any caveat that materially changes interpretation.
  • Include a small stats overview table near the top.
  • Include a repository overview table with Markdown links to the repos when GitHub exposed the repo URLs.
  • Then write 2-3 short body sections that tell the story of the week.
  • Name specific repos and changes inside the prose. Example style: "
    trnscrb
    moved closer to native macOS conventions, with settings-window work explicitly calling out HIG and Liquid Glass patterns."
  • Mention 3-5 standout changes, but weave them into the text instead of turning them into a checklist.
  • Include 2-4 linked highlights near the end, pointing to repos or commits where that helps the report feel concrete.
  • Keep the whole review to about one page total.
  • End with one compact caveat note only if needed: restricted contributions, incomplete visibility, inaccessible repos, or uncertain attribution.
  • 使用output-template.md中的默认结构。
  • 不要返回大段连续段落。最终的Markdown应读起来像一份简洁的报告。
  • 以简短的开篇段落开头，包含关键统计数据：提交数量、仓库数量、主要编程语言，以及任何会实质性影响解读的说明。
  • 在顶部附近添加一个小型统计概览表格。
  • 当GitHub提供仓库URL时，包含带有Markdown链接的仓库概览表格。
  • 然后撰写2-3个简短的正文部分，讲述本周的工作故事。
  • 在正文中提及具体的仓库和变更。示例风格："
    trnscrb
    进一步向原生macOS规范靠拢，设置窗口的工作明确遵循了HIG和Liquid Glass模式。"
  • 提及3-5个突出的变更，但要融入文本中，而非做成清单。
  • 在末尾添加2-4个带链接的亮点，指向相关仓库或提交，让报告更具体。
  • 整个审查报告篇幅控制在约一页。
  • 仅在必要时添加一个简洁的说明：受限贡献、可见性不完整、无法访问的仓库或归属不确定。

Troubleshooting

故障排除

  • Only verify GitHub access if the data collection step fails or returns clearly wrong results.
bash
gh auth status
gh api rate_limit
  • Do not require extra GitHub scopes by default.
  • Open github-collection-notes.md if the contribution totals and visible commit set do not line up cleanly.
  • 仅在数据收集步骤失败或返回明显错误结果时，才验证GitHub访问权限。
bash
gh auth status
gh api rate_limit
  • 默认情况下不需要额外的GitHub权限范围。
  • 如果贡献总数与可见提交数据集不完全匹配，打开github-collection-notes.md。

Output Standard

输出标准

  • Prefer Markdown if writing to a file.
  • Keep the tone reflective and concrete.
  • Use stats to anchor the story, not to dominate it.
  • Use report structure: heading, one-line deck, stats table, repository table, prose sections, compact highlights.
  • Link repo names with standard Markdown links whenever the repo URL is known, including private repos that were explicitly surfaced by the authenticated GitHub query.
  • Avoid raw commit dumps, long bullet lists, or one-sentence-per-commit writing.
  • Avoid filling the whole page with caveats. The caveat note should stay short unless the data is genuinely unusable.
  • 如果写入文件，优先使用Markdown格式。
  • 语气应具反思性且具体。
  • 用统计数据支撑叙事，而非主导叙事。
  • 使用报告结构：标题、一行摘要、统计表格、仓库表格、散文章节、简洁亮点。
  • 只要知道仓库URL，就用标准Markdown链接关联仓库名称，包括已认证GitHub查询明确显示的私有仓库。
  • 避免原始提交转储、长要点列表或每个提交一句话的写法。
  • 不要用说明填满整页。除非数据确实无法使用，否则说明应保持简短。

Anti-Patterns

反模式

  • Do not treat the helper script as mandatory.
  • Do not brute-force every accessible repository when a few repos clearly dominate the review.
  • Do not claim details for restricted contributions. Say they exist, not what they were.
  • Do not require 
    gh auth refresh -s user
    unless the user explicitly wants deeper email-based matching.
  • Do not write from commit headlines alone if the repo context is available.
  • Do not paste raw JSON or raw API dumps into the final review.
  • Do not omit repo links and stats when the data is available.
  • 不要将辅助脚本视为必需工具。
  • 当少数仓库明显主导审查内容时，不要强行遍历所有可访问的仓库。
  • 不要声称受限贡献的细节。只需说明其存在，而非具体内容。
  • 除非用户明确需要更深入的基于邮箱的匹配，否则不要要求执行
    gh auth refresh -s user
    。
  • 如果仓库上下文可用，不要仅根据提交标题撰写内容。
  • 不要在最终审查中粘贴原始JSON或原始API输出。
  • 当数据可用时，不要省略仓库链接和统计数据。

Resources

资源

  • references/output-template.md Default Markdown structure for the final review.
  • scripts/collect_commit_review.py
    Optional helper for broad repo discovery and compact briefing when manual collection is too slow.
  • references/github-collection-notes.md Open when debugging data gaps, tuning limits, or changing the GitHub collection strategy.
  • references/output-template.md 最终审查的默认Markdown结构。
  • scripts/collect_commit_review.py
    当手动收集过慢时，用于广泛仓库发现和简洁简报的可选辅助工具。
  • references/github-collection-notes.md 调试数据缺口、调整限制或更改GitHub收集策略时打开。