Stakeholder Writeup

Stakeholder Report Writeup

Core principle

Every factual claim in a stakeholder report must trace to either (a) a concrete command output / API response in this conversation, or (b) an explicit statement from the user. If a fact has no source, don't write it — don't estimate, don't infer, don't fill in reasonable-sounding defaults.

Stakeholder version ≠ shortened technical doc. It's a different genre: plain language, sourced numbers, honest uncertainty, clear scope, explicit anti-patterns.

Language policy

This skill defaults to English output. Switch to Chinese output if any of these hold:

• The user's last 3 messages are primarily in Chinese.
• The conversation history in this session is primarily Chinese.
• The user explicitly requests Chinese ("用中文" / "中文版" / "Chinese please").

The workflow instructions below stay in English regardless. Only the produced report (section headings, closer, audience prompt) switches language. A side-by-side translation map for section names lives in step 6.

When to use

• User wraps a multi-turn investigation and asks for a document artifact
• Audience is a decision-maker or mixed group (technical lead / executive / PM / business / customer)
• Output is persistent markdown, not chat prose

When NOT to use

• User is asking a quick question, not for a document
• Investigation isn't done — root cause still unknown
• Audience is engineers only (write a technical RCA instead, jargon is fine)
• Context is <3 messages — there's no investigation to summarize

Workflow (7 steps)

0. Confirm language and audience FIRST (before any writing)

Detect the output language (per "Language policy" above) and ask the user which audience this report is for. Present as a numbered choice in the detected language. Skip this step only if the conversation already makes it unambiguous (e.g. user said "for the CTO" / "给客户的" / "write this for the CEO").

English prompt:

Before I start, confirm the audience:
  1) Technical lead (keeps SQL / component tables / jargon is OK)
  2) Non-technical executive (CEO / CFO — drop SQL appendix, use analogies, 60-100 lines)
  3) PM / Business / Product (emphasize user impact, timeline, product-side asks)
  4) External customer (soft tone, liability statement, no internal architecture)
Reply with a number.

Chinese prompt:

开始写之前先确认受众类型：
  1) 技术 leader（懂技术，可保留 SQL / 组件表 / 术语）
  2) 不懂技术的高层（CEO / CFO / 大老板 —— 去 SQL 附录，加类比，篇幅 60-100 行）
  3) 产品 / 业务 / PM（重点写用户影响、时间线、是否需要改产品）
  4) 外部客户（语气软化、责任声明、不谈内部架构）
你回一个编号。

Store the choice and use it to tune step 6.

1. Re-read the conversation (don't write from memory)

Scroll back through the conversation. List:

• Triggering symptom
• Root cause (or "root cause not confirmed" — say so explicitly)
• User-stated business constraints (common rule-outs: "can't add caching" / "architecture frozen" / "must be real-time" / "read-only" — in Chinese: "不能加缓存" / "架构冻结" / "必须实时" / "只读")
• Actions already taken
• Open / unconfirmed items

2. Classify every fact before writing

Build a private mental list of every factual claim you plan to include. For each:

• Source A – command output / API response in this conversation
• Source B – explicit user statement
• Source C – your estimation or inference → must be re-verified or dropped
• Source D – ambient assumption / reasonable default → same treatment

Dangerous claim types that often get fabricated (watch these specifically):

• Severity level (P0/P1/P2) — only if user or a real alerting system assigned it
• Dates / timestamps — only if in conversation
• Counts and percentages — only from aggregate queries, never hand-summed samples
• Causation — "because X, therefore Y" only if evidence chain exists
• Scope claims — "affects all users" only if confirmed, otherwise "scope pending confirmation"

3. Verify C/D facts OR mark them explicitly uncertain

For each C/D class claim, either:

• Re-verify: run a fresh read-only query (SHOW VARIABLES / COUNT(*) / API / log grep) and upgrade to A
• Drop: remove from the report
• Mark: write with ⚠️ and explicit hedge ("~300 transactions, estimated from 20/min × 15min; actual failure count not measured" / "约 300 笔，基于 20笔/分 × 15分 的粗估，实际失败数未统计")

Never let a C/D claim appear in the body as a bare fact.

4. Enforce business constraints

Re-read user messages for rule-outs. Any option the user explicitly rejected:

• MUST NOT appear in top recommendations
• If discussed, mark clearly: 🚫 NOT ALLOWED — {reason stated by user}

5. Plan coverage scope

If the investigation touched multiple components (services, DB instances, regions, environments), write a coverage table.

English:

Chinese:

Without this table, stakeholders assume "all fixed" and later find untouched components → trust lost.

6. Write md using the skeleton (all sections required unless marked optional), tuned by audience

Base skeleton — English

# {System} {Incident/Alert Type} Analysis

> One-liner: **{risk level / core finding}; {what was done / main recommendation}.**  ≤15 words

---

## What happened
{Symptom. For audience 1: original SQL / log / error in full. For audiences 2/4: plain-language version only.}

## Why it happened
{Technical mechanism. Jargon density scales with audience — see variants below.}

## Actual impact (honest assessment)
{Use percentages of capacity, not scary absolutes. Say "no user-visible impact" if true. Separate confirmed from estimated with ⚠️ markers.}

## The real issue
{If alert noise vs real issue: distinguish. List what's actually hiding behind the noise.}

## What we did
| Where | Before | After |
| ... | ... | ... |

## Scope of this pass  【REQUIRED if multi-component; simplify for audience 2】
{Coverage table from step 5.}

## Follow-ups
{Non-urgent items.}

### What NOT to do  【REQUIRED, ≥4 items — ALL audiences】
- ❌ **{antipattern}** — {why not}
- ❌ **{rejected option}** — 🚫 {user's rejection reason}
- ...

{AUDIENCE-SPECIFIC CLOSER — see variants below}

---

## Appendix · Evidence (read-only, {date})
{Raw command outputs, SQL, API responses, timestamps. REQUIRED for audience 1; OMIT entirely for audiences 2 and 4; KEEP but trim for audience 3.}

Section-name map: English ↔ 中文

When writing in Chinese, swap the English headings for these:

Skeleton variants by audience

Closer variants (REQUIRED, pick one by audience)

1-Technical lead (5-row summary)

English:

## Executive Summary (for Tech Lead)  【REQUIRED】
- **Risk level**: Low / Medium / High ({reason})
- **Decision needed?**: No / Yes ({what decision})
- **Resources**: {person-days / budget / external dependencies}
- **Timeline**: {urgent / this week / any time / already done}
- **Open items**: {if any}

中文:

## 执行摘要（给技术 leader）  【REQUIRED】
- **风险等级**：低 / 中 / 高 ({reason})
- **是否需要决策**：否 / 是 ({what decision})
- **资源需求**：{人天 / 预算 / 外部依赖}
- **时间线**：{紧急 / 本周 / 可随时 / 已完成}
- **待跟进**：{如果有开放项}

2-Non-technical executive (3-row, colloquial + analogy)

English:

## One-Line for the Executive  【REQUIRED】
- **Is this dangerous right now?**: {analogy, e.g. "like a shelf in the warehouse came loose, but nothing fell off"}
- **Do you need to decide anything?**: {no — the engineering team can handle it / yes — we need {X} budget / people}
- **When will it be fully clean?**: {specific date + one-sentence guarantee}

中文:

## 一句话给老板  【REQUIRED】
- **现在危险吗**：{类比，例如"像是仓库货架有一格松了，但没有货掉下来"}
- **要不要您拍板**：{否——技术团队自己能搞定 / 是——需要 {X} 预算 / 人力}
- **什么时候能彻底干净**：{具体时间点 + 一句保证}

3-PM / Business (4-row, users + timeline)

English:

## Executive Summary (for PM / Business)  【REQUIRED】
- **Users affected**: {count or percentage + what they felt}
- **Impact on launch or features?**: No / Yes ({which feature, which window})
- **Timeline**: {done / this week / next sprint}
- **What product side needs to do**: None / {specific ask}

中文:

## 执行摘要（给 PM / 业务）  【REQUIRED】
- **有多少用户受影响**：{人数或百分比 + 感知程度}
- **会不会影响发布/功能**：{否 / 是（哪个功能、什么时间窗）}
- **时间线**：{已修完 / 本周 / 下迭代}
- **需要产品侧配合的事**：{无 / 有 —— 具体是 ...}

4-External customer (softened, no internals)

English:

## A Note to Our Customer  【REQUIRED】
- **What happened**: {in plain language, without internal architecture}
- **What we've done**: {fix / monitoring / process improvement}
- **What we're doing to prevent recurrence**: {concrete commitment, e.g. post-mortem, monitoring, periodic audit}
- **Questions?**: {contact / SLA reference}

中文:

## 致客户说明  【REQUIRED】
- **事件摘要**：{发生了什么，不讲内部架构}
- **我们已经做的**：{修复 / 监控加强 / 流程改进}
- **后续保障**：{具体承诺，例如复盘、监控、定期巡检}
- **如有疑问**：{联系方式 / SLA 条款引用}

Pre-send self-check (all must pass)

1. ⬜ Language confirmed — output language is EN (default) or 中文 (per rule), consistent throughout
2. ⬜ Audience confirmed (1/2/3/4) — either user picked or conversation made it unambiguous
3. ⬜ Every number / date / severity / percentage in the body has a Source A/B tag in my head (or ⚠️ hedge if unavoidable)
4. ⬜ Every number has a time-window label in context (24h / this incident / past week)
5. ⬜ No fabricated facts — didn't invent severity level, date, component name, or anything else not in conversation
6. ⬜ Before/after numbers have matching measurement basis / 口径 (or mismatch noted)
7. ⬜ Severity / color claims match the actual thresholds used in the code or monitor
8. ⬜ "What NOT to do" / "不要做的事" section exists with ≥4 items
9. ⬜ Coverage section exists (if multi-component) and marks every component (simplified form OK for audience 2)
10. ⬜ Closer section matches the chosen audience variant and uses that variant's fields
11. ⬜ Rejected options carry 🚫 NOT ALLOWED, not soft language like "not feasible at this time" / "暂不可行"
12. ⬜ Jargon density and SQL/log inclusion match the audience row in the variants table (audiences 2/4 body must be zero-jargon; audiences 2/4 appendix must be omitted)

Fail any → fix before sending. Show the user a checklist of pass/fail when they ask "are you sure this is OK?" / "确定没问题吗".

Real pitfalls (typed, from actual runs)

Pitfall examples are kept in their original language — authenticity beats translation. Column headers and Fix text are in English.

Output location

Use this order:

1. If the user gives an explicit output path, write there.
2. If a private stakeholder report archive is configured, write there:

${STAKEHOLDER_WRITEUPS_DIR}/reports/YYYY/MM/YYYY-MM-DD_查询人_修复人_主题.md

Then update the archive indexes:

${STAKEHOLDER_WRITEUPS_DIR}/index.md
${STAKEHOLDER_WRITEUPS_DIR}/index.json

If the archive is a git checkout, commit and push after writing unless the user explicitly says local-only:

cd "${STAKEHOLDER_WRITEUPS_DIR}"
git add reports index.md index.json
git commit -m "Add stakeholder writeup: <topic>"
git push

3. If no archive is configured, default to <project-root>/docs/<topic>-analysis.md. If no docs/ convention exists, ask first.

Private archive rules:

• The archive should be private if reports include internal system names, people, logs, SQL, customer context, or operational details.
• Do not store API keys, passwords, tokens, private keys, raw customer secrets, or full credential-bearing URLs.
• Use a searchable filename: YYYY-MM-DD_查询人_修复人_主题.md.
• Use today's local date only when the report context does not specify a concrete date.
• If query person or repair person is not confirmed, use unknown; do not invent names and do not ask an extra question only for the filename.
• If topic is not obvious, derive a short readable topic from the confirmed symptom/system.

When this skill updates

When you hit a new pitfall — add a row to the table above with its type (Number / Fact fabrication / Uncertainty leak / Language / Scope / Constraint / Structure / Audience / Evidence). The skill gets stronger each iteration.