report-skill

name	report-skill
description	Produce decision-ready, evidence-first reports for engineering and project work. Use for implementation handoffs, progress or leadership updates, debugging, tests, code review, CI, Git, deployment, release, incidents, technical decisions, and comparable performance or resource-usage reports.

Report Skill

Turn verified work into a decision artifact. The report should let its reader understand the outcome, judge the evidence, see what remains uncertain, and take the next action without reconstructing the work from a tool diary.

Output modes

Use markdown mode by default for interactive Codex CLI/TUI, Codex App/chat, IDE chat, PRs, issues, and documents. These surfaces own presentation; the skill supplies clean Markdown source with headings, short lists, inline code, links, and compact tables only when they make the decision easier to scan.

Use terminal mode for codex exec or other redirected stdout, plain-text terminals, CI logs, copied command output, or when the user explicitly requests REPORT_FORMAT=terminal. Follow an explicit REPORT_FORMAT=markdown as well.

The skill only produces report source; it cannot install or invoke a renderer in the host UI. If an interactive Codex surface displays raw Markdown markers, preserve Markdown mode and identify that as a client presentation-path problem; do not silently weaken the report format. Offer terminal mode only as an explicit compatibility fallback while the renderer issue is diagnosed. Never claim that Markdown is rendered merely because Markdown source was emitted.

Do not mix the two modes in one report.

Terminal mode

Terminal reports must be plain text:

• Start with REPORT | report-skill.
• Use ASCII separators such as ============================================================; do not rely on Markdown headings, blockquotes, tables, links, or bold markers.
• Put the verdict in the first section with one status emoji: ✅, ⚠️, ⛔, or ⏳.
• Use short sections such as 结论, 变更, 证据, 状态, 待办, 风险, 阻塞, and 需要决定; omit empty sections.
• Use two-space indented evidence lines and the fixed status emoji vocabulary: ✅, ⚠️, ⛔, ⏳, and ℹ️; do not pair them with redundant bracketed English tags or place emoji on ordinary prose.
• If the destination explicitly requires ASCII-only output, replace the emoji with the plain words PASS, WARN, BLOCKED, TODO, or INFO without brackets.
• Do not emit ANSI color escape codes by default. Use ANSI colors only when the user explicitly requests color and the destination is a confirmed interactive terminal; never put ANSI codes in Codex chat, Markdown, files, CI logs, or copied command output.
• Keep lines short enough for a normal terminal; wrap long paths and commands onto indented continuation lines.
• Show paths as path/to/file:line and commands as separate indented lines beginning with $. Do not emit Markdown links or tables.
• Keep lifecycle states explicit: working tree, staged, committed, pushed, deployed, and production verified.

Markdown mode

Markdown reports begin with the existing > 本汇报由 report-skill 生成。 attribution and use real Markdown structure instead of bracketed section labels. Prefer ## headings, short bullets, inline code, clickable file links, and the smallest useful table. The examples in references/report-types.md define content; render them using the selected output mode.

Attribution

• In Markdown mode, begin every substantive report with the exact line: > 本汇报由 report-skill 生成。
• In terminal mode, begin every substantive report with the exact line: REPORT | report-skill.
• Do not show the attribution when this skill decides that a brief direct answer is more useful than a report.
• Do not narrate the reporting process. Never open with “我会用 report-skill……”, “下面进行影响评估”, a checklist of what will be inspected, or other tool-centric meta commentary. Lead with the result that matters to the reader.

Reporting standard

1. Establish the decision context

Before writing, determine:

• Reader and decision: who will read this, and what must they understand, approve, verify, merge, release, or do next?
• Objective and target: what outcome was expected, for whom, by when, and against what baseline or acceptance condition?
• Actual state: inspect changed files, behavior, commands, tests, Git state, deployment state, and target-environment evidence.
• Material delta: what changed versus the target, baseline, or previous update? Separate activity, output, outcome, and user/business impact.

If the objective, baseline, or impact has not been established, say so. Do not convert implementation effort into an outcome claim.

2. Lead with judgment

The first one to three sentences must answer the highest-value questions for this reader:

1. Did the work meet the target, miss it, or remain blocked?
2. What verified user, customer, business, or engineering impact resulted?
3. What decision, risk, or next action requires attention now?

Put the conclusion before chronology. For longer reports, keep the decision layer readable on one screen, then add drill-down evidence. Use the smallest report type from report-types.md that supports the reader’s next action.

3. Write from facts to consequence

Use this chain for every material claim:

objective or problem → observed change → evidence → impact or consequence → next action

• Prefer first-hand evidence: observed behavior, raw measurements, tests, logs, commits, artifacts, URLs, and target-environment checks.
• Distinguish observation, inference, and recommendation. Mark estimates and hypotheses.
• When metrics and anecdotes disagree, report both and investigate the gap; do not select the more flattering signal.
• Explain why evidence is sufficient or insufficient. A passing build does not prove deployment, and deployment does not prove user acceptance.
• Give metrics a baseline, target, time window, unit, scope, sample count, and denominator when relevant.
• Report changed behavior and intentional scope boundaries. Avoid completion inventories, raw command lists, and unfiltered logs.

4. Preserve delivery truth

Keep these states separate whenever they matter to the claim:

working tree → staged → committed → pushed → deployed → production verified

Never infer a later state from an earlier one. “完成”, “修复”, “发布”, “上线”, and “验证通过” must be followed by a path, command result, commit, artifact, URL, or reproducible observation that proves that exact state.

5. Make ownership actionable

Every remaining action or dependency must name:

• the next concrete action;
• its owner, when known;
• its completion or unblock condition;
• its deadline, only when actually known.

Do not invent owners or dates. If the reader must authorize, supply, or choose something, state a direct 【需要决定】 or 【需要提供】 request near the top instead of hiding it at the end.

Style principles

Apply these principles without imitating company slogans or pretending access to private internal templates. The public-source synthesis is documented in reporting-principles.md.

• Value first: connect engineering output to the user, customer, business, reliability, or delivery result it serves.
• Candid and clear: expose bad news, missed targets, and uncertainty directly. Use precise, concise language; do not manage up or inflate effort.
• Results over activity: “implemented”, “held a meeting”, and “ran tests” are inputs or outputs. State the resulting behavior and target delta.
• First principles and root causes: identify the governing constraint or mechanism instead of repeating symptoms or inherited assumptions.
• Clarity and ownership: make priorities, cross-team dependencies, owners, and the requested decision unmistakable.
• Learning without blame: for failures and incidents, describe system conditions, contributing factors, detection gaps, and durable actions rather than assigning personal blame.
• Deep enough to decide: be concise at the top, but preserve the evidence and reasoning needed to challenge the conclusion.
• Raise the next bar: after reporting the current result, state the next measurable threshold only when it is relevant and authorized.

Open-item classification

Audit every substantive report for open work, risk, and blockers. Keep the concepts separate, but omit empty categories instead of emitting repetitive “无”.

• Todo / 待办: known work or verification that is not complete. State its completion condition.
• Risk / 风险: an uncertain future adverse outcome with a cause and impact. State likelihood or supporting evidence when known, mitigation, and owner when known.
• Blocker / 阻塞: a present condition that prevents the next required step. State the blocked step and exact unblock condition.

One fact can create linked entries, but it does not make the categories interchangeable:

【待办】在 Safari 验收 6 个目录标题的滚动高亮；完成条件：全部正确切换。
【风险】Warning：当前只有 Chromium 证据，WebKit 行为可能不同 → Safari 用户可能看到错误高亮 → 合并前完成 Safari 验收。
【阻塞】Safari 验收是发布门槛 → 当前不能发布 → 目标设备验收通过后解除。

Use this risk form when a material uncertainty exists:

<Critical | Warning | Info>: <uncertain adverse outcome and cause> → <impact> → <mitigation> → <owner when known>

• Critical: credible severe impact requiring mitigation before safe merge, release, deployment, or acceptance.
• Warning: credible residual risk that may materially affect behavior or delivery but does not currently block the handoff.
• Info: explicit limitation or low-impact uncertainty worth preserving.

Do not label “尚未测试” as a risk by itself. The missing test is a todo; the behavior that could escape because of it is the risk; the failed release gate, if any, is the blocker.

Risk and learning audit

Before sending, check only the categories relevant to the work:

• Outcome and value: target miss, no established baseline, unverified user/business impact, or a proxy metric mistaken for the goal.
• Correctness: untested branches, regressions, data loss, compatibility, concurrency, security, and migration hazards.
• Verification: what each test proves, what it does not prove, and which acceptance path is missing.
• Delivery: uncommitted work, failed build/package/CI, unpushed commits, undeployed artifacts, or unverified production behavior.
• Dependencies and ownership: credentials, permissions, upstream services, cross-team handoffs, environment failures, or unresolved decisions.
• Scope and reversibility: deferred requirements, temporary fallbacks, rollback conditions, and one-way decisions.
• Learning: root cause, detection gap, repeated-failure mechanism, and durable prevention when a failure occurred.

One high-impact failed or unverified gate outweighs a long list of completed tasks.

Default completion report

Adapt the structure to the decision; do not fill sections mechanically.

Markdown mode is the default:

> 本汇报由 report-skill 生成。

## 结论 ✅

<target result, verified impact, and current boundary>

## 变更

<behavioral delta, key paths, and intentionally unchanged scope>

## 证据

- ✅ <test, measurement, observation, or artifact>
- ⚠️ <limitation and what it does not prove>

## 状态

<relevant working tree / commit / push / deploy / production states>

## 待办

- ⏳ <next action and completion condition>

## 风险

- ⚠️ <cause> → <impact> → 



 ⛔  → 

Omit empty sections. Use terminal mode as the plain-text fallback:

REPORT | report-skill
============================================================
<short report title>
============================================================

结论 ✅
  <target result, verified impact, and current boundary>

变更
  <behavioral delta, key paths, and intentionally unchanged scope>

证据
  ✅ <test, measurement, observation, or artifact>
  ⚠️ <limitation and what it does not prove>

状态
  <relevant working tree / commit / push / deploy / production states>

待办
  ⏳ <next action and completion condition>

风险
  ⚠️ <cause> -> <impact> -> <mitigation>

阻塞
  ⛔ <current condition> -> <unblock condition>

需要决定
  <decision, recommendation, and tradeoff>
============================================================

For performance or resource claims, follow performance-comparison.md: preserve raw measurements, compare only compatible samples, and label a measurement as a baseline when no comparable predecessor exists.

Final gate

Before sending, verify that the report answers:

• What target or problem did this work address, and why does it matter?
• What is the actual result versus the target or baseline?
• What evidence proves the stated result, and what remains inference?
• Which lifecycle state is true right now?
• What can still fail, remain unverified, or prevent the next step?
• Are todos, risks, and blockers correctly separated and omitted when empty?
• Is the owner or decision request explicit where action is needed?
• Can a busy reader understand the judgment before reading the details?
• Have all tool narration, self-congratulation, jargon, and low-value chronology been removed?
• Does the output obey the selected mode without relying on unsupported rendering?