--- name: equinix-coe description: | Generate a first draft of an Equinix Correction of Error (COE) report from incident source materials. Trigger on requests like "draft a COE", "write a COE", "start a COE report", "create a correction of error", "incident report", "postmortem draft", or any mention of drafting a COE/postmortem. Also trigger on "/equinix-coe", "gmpo coe", "dio coe", "coe draft", "/equinix-coe gmpo", "/equinix-coe dio". --- # COE First-Draft Generator Generate a publication-ready first draft of an Equinix COE (Correction of Error) report by synthesizing incident source materials through a structured, interactive workflow. This is a **template-driven** skill. Org-specific templates live in `.claude/skills/equinix-coe/templates/`. The template defines the document structure; this skill provides the universal analysis engine and quality rules. ## Quick Start 1. Invoke with `/equinix-coe gmpo`, `/equinix-coe dio`, or just `/equinix-coe` 2. Provide the incident ID (e.g., INC-397478) and basic metadata 3. Follow the 5-phase workflow -- you'll be guided through each step 4. Receive a draft COE, a quality self-score, and a gap report The skill produces two files: - `docs/coe/COE-{INCIDENT_ID}-draft.md` -- the COE document - `docs/coe/COE-{INCIDENT_ID}-gaps.md` -- checklist of what still needs filling in --- ## Template Selection Before anything else, determine which org template to use. 1. If the user specified an org (e.g., "GMPO COE", "DIO COE", `/equinix-coe gmpo`), use that. 2. If a template path was provided (e.g., `--template path/to/custom.md`), use that. 3. Otherwise, list the available templates in `.claude/skills/equinix-coe/templates/` and ask: > Which org template should I use for this COE? **Available templates:** List all `.md` files in `.claude/skills/equinix-coe/templates/` (excluding `README.md`). For each, read the YAML frontmatter and display the `org` and `org_full_name` fields. If no templates are found, tell the user to add one per the templates `README.md` instructions. Read the selected template file. Parse the YAML frontmatter for org name and SLA policy. If the template has no YAML frontmatter (no `---` block) or is missing required fields: - Missing `org`: derive from the filename (e.g., `netops.md` → `NETOPS`) - Missing `org_full_name`: use the `org` value - Missing `sla`: warn the user that no SLA is configured and skip SLA-related gap report sections. Do not invent an SLA. ## Template Structure Inventory After reading the template, inventory its structure before proceeding: 1. **Headings**: List all `##` and `###` headings -- these define the output sections. 2. **Metadata table**: Examine the `| **Field** | Value |` table. Every field row (Bar Raiser, Document Status, Review Date, etc.) is a field to collect in Phase 1. 3. **Action items layout**: Count the action item tables. One table = unified format. Multiple tables with category headings = split format. Note the category names (e.g., Pre-Incident/During/Post, Immediate/Long-Term, or any other split). 4. **SLA policy**: Read from frontmatter (`sla.draft_share_days`, `sla.complete_days`). This inventory determines the output format for Phase 5. Do not add sections the template does not have. Do not omit sections the template does have. --- ## Quality Scoring Framework Every COE produced by this skill will be self-evaluated against the Equinix MVP Quality Scoring rubric. The draft should be written to maximize the score -- aim for 6/6. | # | Metric | Scores 1 (meets expectation) | Scores 0 (does not meet) | |---|--------|------------------------------|--------------------------| | 1 | **Completeness** | All template sections present without gaps | One or more sections contains gaps | | 2 | **Timeliness** | Draft completed within org SLA (from frontmatter) | SLA breached | | 3 | **Impact Quality** | Impact includes quantitative data: affected customers/accounts, failed operations/API calls, duration, affected metros/regions, error rates | Only technical symptoms described; no measurable data | | 4 | **RCA Quality** | Root cause explained using >= 5 Why steps or equivalent depth, ending on a systemic root cause (process gap, config issue, ownership gap) | RCA incomplete or ends on a symptom | | 5 | **Action Items Quality** | Every action item has Owner + Due Date + Priority and maps to an identified RCA gap | Missing ownership, dates, or remediation doesn't address root cause | | 6 | **Cross-functional Validation** | All impacted teams participated in validating RCA; action items acknowledged by owners across all affected domains | RCA prepared by a single team without input from other impacted domains | **Score formula**: `Quality % = (sum of 1s across 6 metrics) / 6 * 100` --- ## Workflow Overview ``` Phase 1: Incident Metadata Collection (interactive) Phase 2: Slack Bot Intelligence Gathering (interactive, multi-prompt) Phase 3: Source Material Ingestion (transcript + additional docs) Phase 4: Knowledge Graph Synthesis (internal, no user interaction) Phase 5: COE Draft Generation + Quality Score + Gap Report ``` Do NOT skip phases or rush ahead. The quality of the final draft depends on thorough information gathering in Phases 1-3. --- ## Phase 1: Incident Metadata Collection Ask the user for the following. Accept whatever they have; mark anything missing as `[TBD]`. **Required:** - Incident ID (e.g., INC-397478) - Service / product affected - Incident date in RFC3339 format (YYYY-MM-DDTHH:MM:SSZ) - Severity (P1/P2/P3/P4, include any escalations/downgrades with timestamps) - Author(s) name(s) **Collect every field in the template's metadata table.** If the metadata table includes fields like Document Status, Bar Raiser, Review Date, etc., collect those too. - If the template has a **Bar Raiser** field: ask for the Bar Raiser name. Explain: "The Bar Raiser is an experienced cross-organizational reviewer assigned via auto-generated JIRA ticket by the TPM team, who partners with the COE owner to elevate quality before Ops Review." **If available:** - JIRA COE ticket (e.g., GMPOCOE-124) -- if provided, use the `equinix-jira` skill to pull existing metadata from the ticket - Slack incident channel name/link - PagerDuty incident link - Zoom/Teams bridge recording transcript (VTT, SRT, or text file) - Contributors (people who helped investigate/resolve) - Whether external customers were impacted (yes/no/unknown) - Related COE links (prior incidents with similar root cause or affected service) Store all metadata. Proceed to Phase 2 after collecting what the user can provide. **SLA context:** State the SLA from the template frontmatter. If `sla.draft_share_days` is set, note: "The draft should be shared within {draft_share_days} days of incident resolution." If `sla.complete_days` is set, note: "The complete COE is due within {complete_days} days." --- ## Phase 2: Slack Bot Intelligence Gathering The Slack incident channel contains structured, timestamped data that forms the backbone of the COE. However, Slack bots may produce inaccurate summaries if given vague prompts. Instead of asking for "a summary," provide the user with **specific, targeted prompts** to extract reliable structured data. ### Instructions to give the user: > I'll give you a series of prompts to paste into the Slack bot in your incident channel. > Each prompt extracts a different facet of the incident. After each one, paste the bot's > response back to me. > > **Two options:** > - **One-at-a-time** (recommended): I give you one prompt, you paste the response, I > cross-reference before giving the next. Better accuracy. > - **Batch**: I give you all 8 prompts now. You paste responses as you get them. Faster > if you're short on time. > > Which do you prefer? > > If any prompt doesn't return useful results (the bot says "I don't have enough information" > or gives a clearly wrong answer), just tell me and we'll skip it. ### Prompt Set: **Prompt 1 -- Structured Timeline:** ``` Please produce a timestamped timeline of this incident from the messages in this channel. For each entry, include: (1) the UTC timestamp, (2) who posted or took the action, (3) what happened, and (4) whether this was an investigation step, a finding, a decision, or a resolution action. Format as a markdown table. Include only substantive entries -- skip acknowledgments, emoji reactions, and chatter. ``` **Prompt 2 -- Error Signature and Technical Details:** ``` From the messages in this channel, extract all technical details about the error: the exact exception type and message, the endpoint or service affected, database tables or data stores referenced, specific IDs/keys/values mentioned in error messages, environment details (prod/UAT/staging), and any code references (file names, line numbers, class names, repository names). List each detail with the message timestamp and who provided it. ``` **Prompt 3 -- Hypotheses Tested and Debunked:** ``` List every theory or hypothesis that was proposed in this channel about what caused the incident. For each theory, state: (1) who proposed it and when, (2) what evidence was gathered to test it, and (3) whether it was confirmed or debunked, with the specific message or finding that confirmed or debunked it. This is for the "Debunked Theories" section of a COE document. ``` **Prompt 4 -- Root Cause Chain:** ``` Based on the messages in this channel, what was identified as the root cause of this incident? Trace the causal chain from the user-facing symptom back to the underlying issue. Include: (1) what the user saw, (2) what the immediate technical failure was, (3) what data or system condition caused it, (4) what caused that condition, and (5) why existing safeguards did not prevent it. Cite specific messages for each link in the chain. ``` **Prompt 5 -- People and Roles:** ``` List every person who participated in this incident channel. For each person, summarize: (1) when they first appeared in the channel, (2) their apparent role (e.g., responder, investigator, subject matter expert, incident commander, observer), and (3) their key contributions to the investigation or resolution. Cite the specific messages that demonstrate each contribution. ``` **Prompt 6 -- Resolution Steps and Verification:** ``` Describe the exact steps taken to resolve this incident, based on the messages in this channel. For each step: (1) who performed it, (2) when (UTC timestamp), (3) what was done, and (4) how it was verified as successful or unsuccessful. Include any partial fixes that were attempted but did not fully resolve the issue before the final fix. ``` **Prompt 7 -- Severity and Scope:** ``` From the messages in this channel, extract all information about the incident's severity and scope: (1) the initial severity classification and any changes (escalations or downgrades) with timestamps, (2) which services, endpoints, or features were confirmed affected, (3) which were confirmed unaffected, (4) any mention of customer impact (internal users, external customers, specific accounts), (5) quantitative data about the blast radius (number of affected users, accounts, projects, requests, error rates), and (6) the exact timestamps for when the issue started and when it was fully resolved. ``` **Prompt 8 -- Open Questions and Follow-up:** ``` List every unresolved question, open investigation item, or follow-up action mentioned in this channel after the incident was resolved. For each item: (1) what the question or action is, (2) who raised it, (3) who was assigned or volunteered (if anyone), and (4) what the most recent update is. Separate items into "resolved during the incident" and "still open as of the last message." ``` ### Processing Slack Bot Responses As each response comes in: 1. **Cross-reference** entries across prompts for consistency. 2. **Flag contradictions** to the user: "The timeline says X at 20:15 but the scope data says 20:33 -- which is correct?" 3. **Note gaps**: If a prompt returns nothing useful, mark that facet as needing transcript or user input in Phase 3. 4. **Do not trust attributions blindly**: The bot attributes discoveries to whoever posted in Slack, not necessarily who discovered it (often found first on the Zoom bridge). --- ## Phase 3: Source Material Ingestion Ask the user: > Do you have any of the following additional source materials? > 1. **Zoom/Teams bridge recording transcript** (VTT, SRT, or text file) > 2. **Grafana/Datadog/Splunk screenshots or dashboard links** > 3. **Deployment logs or Argo CD screenshots** > 4. **Any notes you or teammates wrote during/after the incident** > 5. **Related COE reports from prior similar incidents** > > The bridge transcript is especially valuable -- it captures the investigation's dead ends, > debunked theories, and the "aha moment" that Slack messages often miss. ### Cross-Functional Input (Quality Metric 6) Before proceeding, explicitly ask: > Which teams beyond yours were involved in or impacted by this incident? > (e.g., Network, DB, Infra, IAM, upstream/downstream app teams) > > Have any of those teams reviewed the root cause findings yet? > Have they accepted ownership of any remediation actions? > > This matters because a COE that reflects only one team's perspective scores > 0 on Cross-functional Validation. ### Bar Raiser Input If the template's metadata table includes a **Bar Raiser** field, ask: > Has a Bar Raiser been assigned for this COE? (Check the auto-generated COE JIRA ticket.) > > The Bar Raiser is an experienced cross-organizational reviewer who will partner with you > to strengthen the narrative, structure, and completeness before Ops Review. Capturing > their name early helps set quality expectations. > > If assigned, include their name in the document metadata. ### Transcript Processing If a transcript is provided (VTT/SRT format): 1. **Calculate the wall-clock offset**: Extract recording start time from the filename (format: `GMT{YYYYMMDD}-{HHMMSS}`). VTT timestamps are relative to this start time. 2. **Extract high-signal segments**: Focus on: - Root cause discovery moments ("I think I know", "okay so", "that's it", "found it") - Hypothesis statements ("could be", "maybe", "I suspect", "what if") - Debunking moments ("it's not", "that's not it", "ruled out", "doesn't explain") - Key decisions ("let's try", "let's do", "our plan is") - Resolution confirmations ("it's working", "looks good", "fixed", "resolved") - Scope observations ("it's project-specific", "only affects", "doesn't affect") 3. **Ignore**: Filler words, garbled transcription, procedural chatter ("can you hear me", "let me share my screen"), profanity. 4. **Map to participants and roles**: Build a participant table with investigation contributions. ### Cross-Reference with Slack Bot Data - **Prefer Slack timestamps** for when things were posted/formal actions taken - **Prefer transcript attributions** for who actually discovered something - **Use transcript for debunked theories** that never made it to Slack - **Resolve conflicts** by noting both sources and asking the user which is correct --- ## Phase 4: Knowledge Graph Synthesis Internal processing -- no user interaction. Build a structured knowledge graph from all collected information. **Collect ALL data regardless of what sections the template has.** The rendering step (Phase 5) decides where each piece goes. ### 4.1 Timeline Construction Merge all timeline sources into a single, deduplicated, RFC3339-normalized timeline. For each entry: - UTC timestamp (firm or approximate with `~` prefix) - Actor (person or team) - Action/observation - Category: `precursor | trigger | detection | investigation | finding | decision | remediation | verification | resolution | follow-up` - Source: `slack-bot | transcript | user-provided | inferred` ### 4.2 Root Cause Chain Build the causal chain from symptom to root cause: ``` User symptom -> Immediate technical failure -> Data/system condition -> Cause of condition -> Why safeguards failed -> Why not detected earlier ``` ### 4.3 Contributing Factors Inventory List all contributing factors discovered. For each: - Title (use "Noun as Descriptor (Causal Role)" pattern, e.g., "Missing User Records (Root Cause)") - Evidence basis: tag each factor as `(confirmed: Prompt N / transcript / metadata)` or `(inferred — needs verification)`. In the draft, prefix inferred factors with `[VERIFY]`. - Causal role: root cause | contributing factor | trigger | amplifier - Evidence - Source **Always check for these common patterns:** - Cross-team ownership gaps (Team A depends on Team B's data but has no visibility into changes) - Missing safeguards (no FK constraints, no monitoring, no alerting, no error handling) - Trigger-vs-root-cause confusion (deployment triggered it but data corruption was the cause) - Blast radius amplifiers (a filter that doesn't work, a query that fetches more than needed) ### 4.4 Investigation Hypotheses For each theory investigated and ruled out: - Theory description - Who proposed it and when - What evidence disproved it - Why it was a reasonable hypothesis (helps future responders) ### 4.5 Impact Assessment - Services affected vs. confirmed unaffected - Customer impact (internal/external, quantified if possible) - Blast radius (per-project, per-account, per-endpoint, per-metro) - Error rates/counts if available - Business KPI linkage: downtime cost estimate, SLA breach risk, customer satisfaction impact - Metros impacted (specific list) - Customer contacts count - Failure rate metrics ("API calls failed XX% of the time") - Graphs needed: time/impact, calls failed, recovery progression ### 4.6 Recurring Pattern Check From the COE Framework's predictive analysis goal, explicitly analyze: - Has this root cause or failure pattern appeared in prior incidents? - Are there related COEs? If the user provided them or they were found via Slack bot, cross-ref. - What systemic condition allowed this to recur? ### 4.7 Gap Analysis Identify what information is still missing or uncertain: - `[VERIFY: description]`: We have a value but need user confirmation - `[TBD]`: We don't have this information at all - `[FIGURE: description]`: A screenshot/dashboard reference should be inserted - `[LINK: description]`: A URL should be inserted --- ## Phase 5: COE Draft Generation + Quality Score + Gap Report ### 5.0 Template-Aware Rendering Generate the COE by filling the template's sections. The template structure inventory (from the start of the workflow) determines the output format. **Section mapping rules:** - For every `##` or `###` heading in the template, populate it with the corresponding synthesized data from the knowledge graph. **Match semantically, not by exact name.** The template's headings are authoritative — use whatever heading names the template uses. - **Debunked / ruled-out hypotheses:** If the template has ANY section whose purpose is listing investigated-and-dismissed hypotheses (e.g., "Debunked Theories", "Ruled-Out Hypotheses", or similar), populate it with Phase 4.4 data. If the template has NO such section, **you MUST still include all investigated-and-debunked hypotheses.** Place them in the most semantically appropriate section — a root cause narrative, a contributing factors section, or the questions section. Do not drop this data — debunked theories are high-value investigation context for future responders. Every hypothesis from Phase 4.4 must appear somewhere in the draft. - **Impact detail:** If the template has a subsection for per-system, per-service, or per-component impact breakdown (e.g., "Per-Service Impact Detail", "Affected Systems"), structure impact data accordingly with contributors and evidence. - **Background / context:** If the template has a section for background or service context, provide it for readers unfamiliar with the service. - **Learnings / recommendations:** If the template has a section for operational insights, learnings, or recommendations, capture insights grounded in incident data — not general engineering wisdom. - **Action items:** If action items use a single table, present all items unified. If split into multiple tables under category headings (whatever the categories — Pre/During/Post, Immediate/Long-Term, or any other split), distribute items to the appropriate category based on the heading name and its HTML comment guidance. - Data from the knowledge graph that doesn't map to any template section should be noted in the gap report under "Questions for the Author." - Do NOT add sections that don't exist in the template. Do NOT omit sections that do. ### 5.1 Writing Principles These principles are derived from analyzing the difference between good and great COEs, aligned to the 6 quality metrics. They apply universally regardless of template. #### Targeting Completeness (Metric 1) - Fill EVERY section of the template. No section may be left empty. - If information is unavailable, insert a `[TBD]` placeholder -- never omit the section. #### Targeting Impact Quality (Metric 3) - Impact section MUST include quantitative data. A vague impact description scores 0. - Include: number of affected customers/accounts, number of failed requests/operations, duration, affected metros/regions, error rates/percentages, success rates. - If quantitative data is unavailable, use `[TBD: number of affected customers]` -- never write "some customers may have been impacted." - Lead with user/business impact, then technical detail: "The landing page was broken for N users" before "the /api/v1/topology endpoint returned 500s." - Link to business KPIs where data exists: estimated downtime cost, SLA breach, CSAT impact. - Include graph placeholders where the template indicates them: `[FIGURE: time/impact graph]`, `[FIGURE: calls failed graph]`, `[FIGURE: recovery graph]`. #### Targeting RCA Quality (Metric 4) **Five Whys rules:** - Each "why" traces exactly ONE causal link deeper. Do not skip levels or combine causes. - The chain MUST reach >= 5 levels deep. - The final "why" MUST end on a **systemic root cause**: a process gap, configuration issue, missing safeguard, or ownership gap -- NOT on a symptom or proximate technical failure. - More than 5 levels is fine if the causal chain warrants it. - Test: if the final answer starts with "because the code/data/config was wrong," go deeper -- ask why the code/data/config was allowed to be wrong. - If source data only supports N confirmed causal links (N < 5), write exactly N confirmed Whys. Then add: `{N+1}. Why? [TBD — deeper analysis requires additional data.]` Do not write speculative Whys with [TBD] answers — a clean [TBD] is better than the appearance of analysis that doesn't exist. **Contributing Factors:** - Each factor gets a descriptive title with causal role label: "Missing User Records (Root Cause)", "Deployment as Trigger (Not Root Cause)" - Explicitly distinguish trigger from root cause: "X was the trigger, not the root cause." - State the ABSENCE of safeguards explicitly: "no database-level FK constraint exists," "no monitoring on referential integrity." - Identify the one-sentence architectural insight that explains the failure. **If Contributing Factors and Five Whys are a combined section in the template** (single heading), the Five Whys chain should flow naturally from the contributing factors narrative. Each "Why" still traces exactly one causal link deeper. **If they are separate sub-sections** (separate headings under a parent), Contributing Factors lists the inventory and Five Whys provides the causal chain independently. **If the template has a single flat RCA section** (e.g., "Root Cause" with no Contributing Factors or Five Whys sub-headings), weave ALL root cause data — contributing factors, Five Whys causal chain, and trigger-vs-root-cause distinctions — into a single cohesive narrative. The narrative must still reach >= 5 levels of causal depth and identify contributing factors with causal role labels, even though they aren't in separate sections. #### Targeting Action Items Quality (Metric 5) - Every action item MUST have: **Owner** (specific person or team), **Due Date** (or `[TBD: due date]`), **Priority** (Critical/High/Medium/Low), and **RCA Link** (which contributing factor or Five Whys step this addresses). - If the template's action item comments mention PCOE_AI JIRA labeling, all JIRA action items must be labeled with `PCOE_AI` per the COE Action Item Tracking process. - Action items should specify **desired outcomes**, not implementations: "Add graceful handling with explicit logging for debuggability" NOT "Add try-catch with LEFT JOIN or @NotFound annotation." - Consolidate items that would naturally be done together by the same person(s). - Every RCA gap identified should have at least one corresponding action item. - After assigning priorities, compute suggested due dates from the COE date using priority tier windows (Critical: +2 weeks, High: +4 weeks, Medium: +8 weeks). Present as `[SUGGESTED: YYYY-MM-DD based on {Priority} tier]` rather than bare `[TBD: due date]`. - When source data contains relative time estimates ("2-3 days", "end of sprint"), convert to approximate dates from the incident date. #### Targeting Cross-functional Validation (Metric 6) - Note which teams contributed to the RCA in the document itself. - In formal sections (Summary, Impact, Root Cause, Contributing Factors), attribute actions to **teams**: "the NE team confirmed..." not "Suneeth confirmed..." - In the Timeline section, individual names are appropriate for precision. - Flag in the gap report which teams still need to validate the RCA and accept action items. #### General Principles **Tone:** - Blameless. Focus on systems, processes, and conditions -- not individuals. - No hedging or speculation. If something is unknown, use `[TBD]` once, not "possibilities include X, Y, or Z." **Source Discipline:** - Before writing any factual claim (timestamp, number, technical detail, process statement), verify it traces to a specific provided source: a metadata field, a Slack bot prompt response, a transcript segment, or a user statement. - When a source mentions an action was *started* or *initiated* but does not report its result, mark the result as `[TBD]`. Do not infer outcomes from actions being taken. - Never present an inference as an established fact in ANY section — including Background, Learnings, Debunked Theories, Summary, Per-Service Impact, Other Questions, and Five Whys question text. If a detail is not directly stated in source data, either omit it or mark it `[VERIFY: inferred from X]`. - **No section is exempt from source discipline.** Architectural claims (capacity numbers, system design descriptions, mechanism explanations) must trace to source data. Do not inject general engineering wisdom or process recommendations that no participant articulated. In any debunked/ruled-out hypotheses section, state what was investigated and what evidence disproved it — do not add "this was a reasonable hypothesis because..." explanations sourced from general domain knowledge rather than incident data. - **[VERIFY] tagging must be consistent across sections.** If an inference is tagged `[VERIFY]` in Contributing Factors, the same inference must carry the same tag when it appears in Background, Learnings, Summary, or Five Whys question text. One inference, one tag, everywhere it appears. - **Do not fill ambiguity gaps with invented specifics.** When data contains a gap (an unexplained percentage, an unknown timestamp, a missing action item), leave the gap visible rather than manufacturing a plausible explanation. Write `[TBD]` or omit the claim. Never invent a timestamp for an event whose timing is unspecified, fabricate an explanation for an unexplained metric, or generate action items from general engineering knowledge rather than source data. Action items synthesized from observed incident behavior — but not explicitly proposed by any participant — must carry `[VERIFY: inferred from observed behavior, not explicitly proposed]` tags. - **Exclude data from concurrent incidents.** If source materials contain data from a different incident (e.g., shared Slack channels with cross-posted messages from another team's issue), identify and exclude that data. Document the exclusion in the gap report. - **Resist confidence cascades.** When an unconfirmed theory is repeated across multiple prompts with increasing confidence, do not promote it to confirmed status. A single explicit disconfirmation ("not confirmed," "still investigating") overrides any amount of accumulated circumstantial support. Tag with `[VERIFY]` and note the conflicting evidence. **Structure:** - Each section adds new information. Don't repeat the same explanation across multiple sections. - The questions section (whatever it's called in the template) contains only questions whose answers provide genuinely new information not covered elsewhere. - Questions must not contain speculative answers, invented thresholds, or recommendations. State what is unknown and why it matters — do not propose ungrounded explanations. Use `[TBD]` for answers, not hedging. **Precision:** - All timestamps in RFC3339 format (YYYY-MM-DDTHH:MM:SSZ). - Use firm numbers when available. Flag uncertain values with `~` prefix. - Provide exact timestamps. Flag uncertain ones with `[VERIFY: ...]`. - When computing durations, re-verify the arithmetic. If your computed duration differs from a duration explicitly stated in source data, note both values with `[VERIFY]` in the gap report. **Placeholders:** - `[VERIFY: description]` for values that need user confirmation - `[TBD]` for missing information - `[FIGURE: description of needed screenshot/dashboard]` for visual evidence slots - `[LINK: description]` for URLs to be filled in ### 5.2 Quality Self-Score After generating the draft, evaluate it against the 6 metrics. For each metric, score 1 or 0 with a brief justification: ```markdown ## Quality Self-Score | # | Metric | Score | Justification | |---|--------|-------|---------------| | 1 | Completeness | 1/0 | [All sections present / Section X has gaps] | | 2 | Timeliness | N/A | [Skill accelerates this; note days since incident closure] | | 3 | Impact Quality | 1/0 | [Quantitative data present / Only symptoms described] | | 4 | RCA Quality | 1/0 | [>= 5 Whys ending on systemic cause / Ends on symptom at Why N] | | 5 | Action Items Quality | 1/0 | [All items have Owner+Date+Priority+RCA link / Items X,Y missing fields] | | 6 | Cross-functional Validation | 1/0 | [N teams contributed / Only 1 team's perspective] | **Score: N/5** (Timeliness excluded from skill-generated score) **Quality %: NN%** (N/6 * 100, including Timeliness as N/A -> 0 for conservative estimate) ``` ### 5.3 Review Feedback (for metrics scoring 0) For each metric that scores 0, generate targeted feedback using the Review Pattern: ```markdown ### Metric N: [Metric Name] -- Score: 0 **Location:** [Exact section or element with the gap] **Gap:** [Factual, neutral description of what is missing or incomplete] **Guiding question:** [Short question to help the author fill the gap] ``` This feedback goes in the gap report, not the COE draft itself. ### 5.4 Gap Report The gap report prioritizes items requiring human judgment (ambiguous root causes, cross-team validation gaps, missing quantitative data, unresolved investigation threads) over mechanical blanks. The skill handles the drudgery; the gap report focuses your attention on the non-obvious. Produce a separate gap report. Adapt the structure to the template — include sections that are relevant based on the template's features: ```markdown # COE Draft Gap Report -- {INCIDENT_ID} ## Quality Self-Score Summary [Include the score table from 5.2] ## Review Feedback [Include targeted feedback from 5.3 for any metric scoring 0] ``` If the template has a **Bar Raiser** metadata field, include: ```markdown ## Bar Raiser Review Status - [ ] Bar Raiser assigned: {{BAR_RAISER_NAME}} or [TBD] - [ ] Draft shared with Bar Raiser by: [target: incident resolution + {draft_share_days} days] ``` If the template frontmatter has **SLA** policy, include: ```markdown ## SLA Tracking - Incident resolved: {{RESOLUTION_DATE}} - SLA target(s): [computed from frontmatter sla values] ``` Then always include: ```markdown ## Timestamps to Verify - [ ] [VERIFY: description] -- source and what to check against ## Missing Information - [ ] [TBD] description ## Figures to Capture - [ ] [FIGURE: description of needed screenshot/dashboard] ## Links to Add - [ ] [LINK: description] ## Action Items Needing Completion - [ ] Action item X: needs owner / due date / JIRA link ## Cross-Functional Validation Needed - [ ] [Team name]: needs to review RCA and accept action items ## Questions for the Author - [ ] [Specific question about a conflict or ambiguity] ## Strategic Questions - [ ] [Second-order implications: downstream customer impact needing SLA credits or proactive communication, data source limitations affecting verifiability, recurring patterns warranting broader review beyond immediate action items] ``` ### 5.5 Output Save the draft to `docs/coe/COE-{INCIDENT_ID}-draft.md` and the gap report to `docs/coe/COE-{INCIDENT_ID}-gaps.md`. Present a summary to the user: - Quality self-score (N/5 + which metrics scored 0) - Sections completed vs. sections with significant gaps - Top 5 items that would most improve the draft if filled in - SLA targets (computed from frontmatter) - Suggested next steps (e.g., "get NE team to validate RCA," "confirm customer impact numbers") --- ## Quality Checklist (Self-Review Before Presenting) Before presenting the draft, verify these universal quality standards: - [ ] Summary is 2 paragraphs: (1) what happened + user impact, (2) technical root cause - [ ] Trigger vs. root cause is explicitly distinguished - [ ] Customer impact is stated with quantitative data or flagged as `[TBD]` -- no speculation - [ ] Impact section includes numbers: affected customers, failed operations, duration, scope - [ ] Contributing factors each have a descriptive title and causal role label - [ ] Five Whys traces >= 5 levels deep, each step one causal link, ending on systemic cause - [ ] All timestamps use RFC3339 format (YYYY-MM-DDTHH:MM:SSZ) - [ ] Action items have Owner + Due Date + Priority + RCA Link (or `[TBD]` placeholders) - [ ] Every RCA gap has at least one corresponding action item - [ ] No individual blame language; teams attributed in formal sections - [ ] Cross-team dependencies and ownership gaps are surfaced as contributing factors - [ ] The one-sentence architectural insight is clearly stated - [ ] Every `[TBD]`, `[VERIFY]`, `[FIGURE]`, `[LINK]` is captured in the gap report - [ ] Related/prior COEs referenced if available - [ ] Quality self-score computed and presented - [ ] [VERIFY] tags are consistent: same inference carries the same tag in every section - [ ] No fabricated gap-filling: unexplained metrics, unknown timestamps, and unsourced action items are [TBD] or omitted, not invented - [ ] Synthesized action items (inferred from behavior, not explicitly proposed) carry [VERIFY] - [ ] Five Whys [TBD] steps contain only the [TBD] marker — no inferred explanations inside - [ ] Gap report includes strategic questions beyond direct gaps: downstream customer impact, data source limitations, recurring pattern implications - [ ] No section is exempt from source discipline — all checked for inference-as-fact - [ ] All debunked hypotheses from Phase 4.4 appear in the draft — either in a dedicated section for ruled-out hypotheses (whatever the template calls it) or woven into the root cause / contributing factors / questions narrative Then verify template-specific standards (check every section present in the template): - [ ] Every section in the template is populated (or has [TBD] placeholders) - [ ] No sections were added that don't exist in the template - [ ] If template has a background/context section: provides service context for unfamiliar readers - [ ] If template has a learnings/recommendations section: grounded in incident data, no general engineering wisdom - [ ] If template has a debunked theories / ruled-out hypotheses section: each theory states the evidence that disproved it - [ ] If template has an impact breakdown section (per-service, per-system, etc.): structured per the template's format with contributors and evidence - [ ] If template has split action item tables: items distributed to correct categories per the template's category names - [ ] If template has unified action item table: all items in one table - [ ] If template mentions PCOE_AI: JIRA action items labeled accordingly - [ ] Every metadata table field from the template is populated or flagged [TBD] - [ ] Questions / unresolved items section uses the heading name from the template - [ ] Questions / unresolved items section has no entries redundant with other sections - [ ] Questions / unresolved items section does not contain speculative answers - [ ] Novel sections not present in other templates (e.g., Executive Summary) are populated with appropriate content based on the section's heading and HTML comment guidance