write-weekly-report-email

name

write-weekly-report-email

description

Create concise, manager-ready Chinese internship weekly report emails from specified Git repositories, user notes, local reports, TODOs, tests, and optional PR/Issue/review evidence. Use when Codex needs to draft, shorten, human-edit, validate, or render a weekly internship report, 周报邮件, Outlook-compatible HTML report, monthly-goal progress, contribution metrics, blockers, or next-week plans in the supplied Word/Outlook intern report format.

Write Weekly Report Email

Produce a manager-ready weekly report whose claims can be traced to user notes, repository records, tests, or community activity. Make the result understandable in a 15-second scan. Generate the email subject, structured data, and Outlook-compatible HTML; never send the email without a separate explicit confirmation.

Use a local-first evidence policy. Treat repositories, worktrees, reports, TODOs, benchmark files, test logs, and Git history on the current machine as the primary source for development work. Query GitHub only for PR/issue/review conversation data or current upstream state that local files cannot authoritatively provide. Never query remote profiles to infer internal identity fields.

Inputs

Resolve these inputs before drafting:

• Reporting period, inclusive start and end dates.
• One or more repository paths.
• Internship role, reporter, mentor, and direct manager from WEEKLY_REPORT_ROLE, WEEKLY_REPORT_REPORTER, WEEKLY_REPORT_MENTOR, and WEEKLY_REPORT_MANAGER, or explicit current-turn input.
• User-provided learning notes, meetings, non-Git work, risks, and intended next steps.
• PRs opened and merged, PRs substantively reviewed, Issues substantively analyzed, and actionable proposal comments when community work is in scope.
• Git author identity when it differs from repository user.email / user.name.
• Output directory and week number when repository naming rules require them.

Keep role and identity values in process environment variables or an ignored local .env; do not commit them in the skill or report-data JSON. Never infer role or identity from a public profile or from the example email. Ask only for values that cannot be discovered safely. Never infer learning outcomes, completion state, or business impact from a commit title alone.

Workflow

1. Read Repository Rules

Read applicable AGENTS.md files and the repository's current progress/state file before collecting evidence. Follow local naming, privacy, branch, report, and commit rules.

For AgentCube, read root PROGRESS.md, relevant internship-reports/week*-summary.md, daily reports for the period, and internship-reports/todo.md. Continue an existing weekly record when repository rules require it.

2. Collect Git Evidence

Discover relevant local repositories and worktrees first. Prefer one canonical repository with --scope all when its refs cover related worktrees; avoid double-counting the same commits from multiple worktree paths. Add another --repo only when it has an independent Git object database or contains separate task history.

Run the collector once with all repositories:

python3 .agents/skills/write-weekly-report-email/scripts/collect_git_evidence.py \
  --repo /path/to/repo-a \
  --repo /path/to/repo-b \
  --since YYYY-MM-DD \
  --until YYYY-MM-DD \
  --output /tmp/weekly-git-evidence.json

Use --author <pattern> when repository Git identity is missing or the report must cover another explicit author. The collector searches all refs by default so topic-branch and fork work are not lost; use --scope current only when the user requests current-branch evidence.

Treat collected commits as evidence candidates, not report rows. Read relevant local diffs, tests, reports, and logs before stating why work mattered or whether it was complete. Fetch GitHub PR/issue/review data only when the claim depends on current upstream conversation or state. Separate:

• Work authored by the reporter.
• Reviews, tests, or analysis performed on another contributor's work.
• Upstream changes merely fetched into the repository.
• Local experiments that were not submitted or merged.

3. Build an Evidence Matrix And Metrics

Before writing prose, map each intended claim to a source and status. Follow references/report-schema.md for the evidence hierarchy, metric definitions, and content contract.

Count community work from authoritative PR/Issue state, not commit totals. Keep object IDs in activity_metrics so each number can be audited. Distinguish PRs opened during the week from PRs merged during the week; an older PR merged this week belongs only in the latter count. Count a review or proposal point only when it contains substantive analysis or an actionable suggestion.

Use these status rules:

• 已完成: evidence shows the scoped result and its required validation are complete.
• 进行中: work or validation still owned by the reporter remains unfinished in the stated weekly scope.
• 受阻: a concrete blocker prevents progress; name the failed step and current workaround.
• 未开始: planned work has not begun.

For community work, separate the reporter's delivery status from the community's acceptance status. A submitted PR, completed PR Review, posted inline comments, or submitted nomination may be 已完成 for the week even while maintainer review or merge remains pending; state that external status in the detail instead of keeping the reporter's work 进行中. Use 进行中 only when the reporter still owns an unfinished action in the row's scope.

Do not call an open PR merged, a proposal implemented, a compile check an e2e result, or an external author's change the reporter's authored work.

4. Draft For A Manager

Read references/manager-writing-style.md, including its five-section contract. Before writing prose, fill this compact card for every row:

1. 本月目标: project + monthly outcome + status. Keep 2-4 stable outcomes; do not list PRs or tests.
2. 本周进展: workstream + delivered state + number/evidence + value or one remaining risk. Group into 2-4 results.
3. 收获与分享: concrete event + exact technical object + plain-language meaning + future rule. Keep 0-3 judgments that changed a decision.
4. 疑惑与问题: decision context + real choice/blocker + impact. Keep 0-3 questions and omit the section content when no decision is open.
5. 下周计划: object + measurable end state + dependency when material. Keep 1-4 plans with acceptance evidence.

Start with a summary pass before adding any technical detail:

• Write one sentence each for 要做什么, 本周做到哪, and 下一步是什么.
• Use three weekly-progress rows by default. Use two or four only when the work genuinely has fewer or more independent outcomes.
• Keep the complete manager-facing body below 1000 compact characters by default.
• Treat the evidence matrix as the place to prove claims. The email summarizes results, value, risks, decisions, and next actions; it does not reproduce proof chains or theory.
• Replace technical shorthand with ordinary engineering language when the exact term does not affect a manager decision. For code, API, or security design, write 方案, 要求, 规则, or 约束; reserve 合同 for an actual company, legal, procurement, or business contract.

Treat PR and Issue numbers as locators, never as the task description. In every manager-facing row, pair each #number with the repository and a concrete feature, component, bug, or proposal topic. Write WarmPoolAvailable 状态与 Event（AgentCube PR #385）, not 更新 AgentCube #385.

Do not draft 收获与分享 as a low-level technical lecture. Preserve the evidence's necessary object or established term, then explain it. A duration or number must identify its project/component, operation, and object: write WorkloadManager 创建 CodeInterpreter session 时使用的 2 分钟 timer, not the ownerless phrases 代码里设置 2 分钟 timer or 2 分钟计时. A fresh reader must be able to say where the behavior lives, what happened, and what future behavior changes.

Name people by their community role, never by contrast with the agent. Write 维护者, 作者, 审查者, 贡献者, or CI bot as the evidence supports; never write 真人 or 人类 reviewer. Preserve project artifacts and work types such as PR Review, Feature Proposal Review, and inline comments; do not replace them with generic Chinese labels. Replace internal diagnostic labels with their observable effect. Write 自定义 HTTP 方法会不断新增监控数据项, not 高基数指标.

Keep activity_metrics in structured data as audit evidence, but do not add a 本周数据 row. The supplied Word/Outlook template has no such row.

Keep detailed tests, commands, failed paths, root causes, and workarounds in the evidence matrix. Mention them in the email only when they changed a decision, exposed a release risk, or explain a blocker. Do not write routine fork, worktree, branch, checkout, sync, local reproduction, build, lint, or test steps.

5. Create Structured Report Data

Create a UTF-8 JSON file matching references/report-schema.md. Keep within the manager-facing limits enforced by the renderer and content validator:

• 2-4 monthly goals.
• 2-4 weekly progress rows.
• 0-3 learnings.
• 0-3 questions.
• 1-4 next-week plans.

When community work is in scope, add activity_metrics with counts and evidence IDs for opened PRs, merged PRs, reviewed PRs, analyzed Issues, and proposal comment points. Do not store identity data in these fields.

Use plain text only. The renderer escapes HTML and converts embedded newlines to <br>.

6. Human-Edit Without Changing Facts

Automated validation is necessary but never sufficient. After the scripts pass, perform a separate readback using only the final five-section email body; do not approve wording while still looking at the technical evidence or draft notes.

Run the independent review-weekly-report workflow against the exact final body. The report is not ready for handoff unless that review returns READY and states 已完成逐句通读：是. Any later wording or status edit invalidates that verdict for the changed section.

Read every row as if speaking it directly to the manager. For each sentence, answer all four questions before keeping it:

1. Who acted, and is that person's project role named accurately?
2. What concrete object, setting, or number is being discussed?
3. What changed, why does it matter, and what remains open?
4. Would this exact sentence be natural to say aloud without translating internal jargon?

Rewrite any sentence that requires hidden chat context or mental translation. Then read the five sections once more in order to catch repeated wording, inconsistent status, and transitions that are individually valid but collectively confusing. Do not hand off a report merely because the validator returned content ok.

During that readback:

• Put the result or decision before its implementation story.
• Replace abstract verbs with the concrete change, count, status, or effect.
• Reject invented abbreviations, compressed noun piles, and phrases that do not sound natural when read aloud. Use a concrete verb, object, and expected result; never shorten 补充验证 or 补充证据 to 补证.
• Preserve the exact key object before simplifying its meaning. Do not delete timer, mTLS, CRD migration, or another term when a number or conclusion depends on it.
• Preserve established engineering vocabulary and artifact names such as E2E, CI, PR, Issue, PR Review, Feature Proposal Review, inline comments, and merge; do not translate terms mechanically when the technical manager and project already use them. State CI 通过 or CI 失败 directly instead of using 绿灯 or 红灯 metaphors.
• Apply the fresh-reader gate to all five sections: no undefined pronouns, floating durations, unexplained status, or plan without an observable end state.
• Apply the role gate: every person or account must be named by project role, not as human versus agent.
• Apply the effect gate: replace opaque review labels and implementation shorthand with cause -> observable consequence; keep exact internal terminology in the evidence matrix when the manager does not need it.
• Delete any sentence that adds no fact, value, risk, or decision.
• Confirm a manager can identify the three main outcomes and their next actions in 15 seconds without reading the evidence matrix.
• Preserve every number, ID, status, and technical name from the evidence matrix.
• Do not add slang, deliberate mistakes, fake uncertainty, personal anecdotes, or claims intended to defeat AI detectors.

7. Render the Email

python3 .agents/skills/write-weekly-report-email/scripts/render_weekly_report.py \
  --data /path/to/weekN-report-data.json \
  --env-file .env \
  --output /path/to/weekN-weekly-report-email.html

The renderer uses assets/report_template.html and creates a sibling *.subject.txt unless --subject-output is provided. Use references/original-email.html only when checking fidelity against the original Word/Outlook export; it is not the editable template.

The renderer writes to WEEKLY_REPORT_OUTPUT_DIR or the explicit output path without querying GitHub or depending on repository visibility. Before committing or pushing rendered output to a public repository, review the exact files and confirm that every included identity is approved for public disclosure. Use an unversioned temporary path when that approval is absent or uncertain.

8. Validate Before Handoff

Check all of the following:

• Every substantive claim maps to the evidence matrix.
• Dates include the full requested period and do not include later work.
• Status values match actual completion and upstream state.
• No credentials, tokens, private URLs, personal email addresses, kubeconfigs, or confidential logs appear.
• No {{placeholder}} remains in the HTML.
• Subject, internship role, reporter, mentor, manager, and report period are correct.
• HTML opens correctly and retains the five-section table layout.
• File names follow repository rules, including weekN-... prefixes where required.
• The report passes the manager-style content validator in strict mode.
• A separate agent readback of the final five-section body is complete; content ok alone is not approval.

Run:

python3 .agents/skills/write-weekly-report-email/scripts/validate_report_content.py \
  --data /path/to/weekN-report-data.json \
  --strict

python3 .agents/skills/write-weekly-report-email/scripts/validate_report_layout.py \
  /path/to/weekN-weekly-report-email.html

rg -n '\{\{[^}]+\}\}|(OPENAI_API_KEY|GITHUB_TOKEN|GH_TOKEN)[[:space:]]*[:=]|BEGIN .*PRIVATE KEY' /path/to/weekN-weekly-report-email.html

The content validator must report content ok, the layout validator must report layout ok, and the rg result must be empty. Also run the skill validator, representative unit tests, file, ls -lh, and the repository's normal diff checks.

9. Email Sending Gate

Drafting and rendering do not authorize sending. Before any email client, SMTP, Graph API, or other external send action, show the user:

• Exact recipients and CC list.
• Exact subject.
• Final HTML/body and attachments.
• Any remaining uncertainty.

Send only after explicit confirmation of that exact payload. Never discover or guess recipients from Git history.

Output Contract

Return links to:

• The structured report data JSON, without personal identity fields when environment configuration is used.
• The rendered HTML email.
• The subject text file.
• The evidence JSON or local evidence record used to draft it.

Summarize which sources were used, which claims remain 进行中 or 受阻, and whether the email was only drafted or explicitly sent.