Skill Hub — Work Documentation and Handover

Incident Documentation Working Skill

Write an incident record that captures symptom, diagnosis, resolution, and prevention so the next incident is handled faster and patterns are visible.

What this skill is for

Incidents are expensive, but undocumented incidents are more expensive because every recurrence becomes a new investigation. This skill produces an Incident Record: a structured document that captures what happened, how it was detected, what was tried, what worked, and what must change to prevent recurrence. The output is designed to be read by the next on-call engineer, the incident review team, and pattern analysis tools. It is different from incident-triage, which classifies and routes incidents, and from root-cause-analysis, which finds deep causes. This skill documents the incident after it is resolved so the knowledge survives and patterns become visible.

When to use this skill

An incident has been resolved and the team needs to capture the resolution for future reference.
An incident review or post-mortem meeting is scheduled and the team needs a structured record to discuss.
A recurring incident pattern is suspected and the team needs documented evidence to compare symptoms and resolutions.
A new team member needs to understand how previous incidents were handled without asking the original responder.
An AI agent is analyzing incident history to suggest preventive measures or automate detection.
A customer or audit requires evidence of incident handling and resolution.

Real work situations

SAP IDoc failure: documenting a recurring mapping error

A sales order IDoc fails with status 51 in WE02 due to a missing delivery block mapping in SAP PI. The responder fixes the mapping, reprocesses the IDoc, and closes the ticket. Two weeks later, the same IDoc type fails again with the same error. The responder is on vacation. The new responder spends two hours re-investigating because the original ticket only says "mapping fixed, IDoc reprocessed." An Incident Record would have captured: the symptom (status 51, error text "delivery block not found"), the diagnosis (PI mapping missing field for delivery block for new plant 1002), the resolution (update mapping, add plant 1002 to condition table, reprocess IDoc), and the prevention (review PI mapping for all new plants before go-live). Without this record, the organization pays for the same investigation twice.

Background job failure: documenting a timeout pattern

A monthly customer reconciliation job ZCUST_REP fails with a timeout after running for two hours. The basis team increases the job runtime limit and restarts the job. The job completes. The ticket is closed with "runtime limit increased." Three months later, the job fails again. The new basis team member increases the limit again, but the job still fails because the underlying cause is a missing database index on the customer table. An Incident Record would have captured: the symptom (timeout after 2 hours), the diagnosis (runtime limit too low, but also query execution plan shows full table scan), the resolution (increase runtime limit temporarily and create index on KNA1), and the prevention (add index creation to change request for next release). Without the record, the temporary fix becomes the permanent fix and performance degrades.

BP replication failure: documenting a complex multi-system incident

A business partner created in SAP MDG fails to replicate to S/4HANA, blocking a critical sales order. The incident involves MDG, S/4, and a middleware queue. The responder clears the queue, re-triggers the replication, and the BP appears. The ticket is closed. The next week, the same failure occurs. An Incident Record would have captured: the symptom (BP missing in S/4, order blocked), the systems involved (MDG, S/4, SAP PI), the diagnosis (queue worker stuck due to RFC destination timeout), the resolution (restart queue worker, clear SM58, re-trigger replication), and the prevention (add queue depth alert, increase RFC connection pool). Without this record, the incident becomes a chronic mystery.

Inputs required

Incident ticket or alert showing the initial symptom, timestamp, and affected system.
Responder notes showing what was checked, what was tried, and what the results were.
System logs, error messages, screenshots, or trace files from the incident period.
Root cause analysis findings if a separate RCA was performed.
Change records or deployment history showing what changed before the incident.
Communication records: emails, chat threads, or bridge call notes showing stakeholder involvement.
Resolution confirmation: evidence that the issue is resolved and the system is stable.
Prevention plan: what will be changed to reduce recurrence likelihood or impact.

Questions to ask

What was the symptom? What did the user or system report, and when?
What systems, transactions, and programs were involved?
What was the business impact? How many users, orders, or processes were affected?
What was the sequence of events? What happened first, second, third?
What was tried that did not work? Failed attempts are as valuable as successful ones.
What was the actual resolution? What specific action fixed the issue?
What was the root cause? If unknown, say so. Do not guess.
What could have detected this earlier? What monitoring or alert is missing?
What must change to prevent recurrence? If nothing can be done, say so.
Who was involved, and what did each person do?

Working method

Gather the inputs. Collect the ticket, responder notes, logs, screenshots, and communication records. If the responder did not take notes, interview them immediately while memory is fresh.
Write the timeline. Create a chronological sequence of events: detection, initial response, diagnosis, attempts, resolution, and confirmation. Include timestamps. Distinguish what was known at each point from what was discovered later.
Describe the symptom. State what the user or system reported. Include error messages, status codes, transaction IDs, and affected objects. Be specific enough that the next responder can search for the same symptom.
Describe the diagnosis. Explain what was checked, what was found, and what the conclusion was. Include the tools and transactions used: SM58, SM50, WE02, ST22, etc. If the diagnosis was uncertain, state the uncertainty.
Record failed attempts. Document what was tried and why it did not work. This prevents future responders from repeating the same failed attempts.
State the resolution. Describe the exact action that resolved the issue. Include transaction codes, program names, parameter changes, and restart steps. If the resolution was temporary, state that.
State the root cause if known. If a separate root cause analysis was performed, summarize it. If the root cause is unknown, state "Root cause unknown" and describe the leading hypothesis.
Propose prevention. List what will be changed to reduce recurrence or detect it earlier: monitoring, process change, configuration change, training, or documentation. If no prevention is feasible, say so.
Write the Incident Record. Use the template below. Keep it concise but complete. One to two pages is the target.
Review and publish. Validate the record with the responder and the incident review team. Store it in the incident knowledge base with searchable tags.

Decision rules

If the root cause is unknown, do not invent one. State "Unknown" and describe the leading hypothesis.
If the resolution was temporary, label it as a workaround, not a fix. Document the permanent fix separately.
If the incident involved a third party, document the third-party response and any handoffs. Do not hide vendor involvement.
If the incident was caused by a recent change, document the change ID and the rollback option if applicable.
If the prevention plan requires a change request, document the change request ID and the expected completion date.
If the incident is part of a pattern, link to previous incident records and update the pattern analysis.

Deliverables

Incident Record — Structured document capturing symptom, timeline, diagnosis, resolution, root cause, and prevention. See template below.
Timeline Diagram — Optional visual timeline showing events, decisions, and handoffs during the incident.
Prevention Plan — List of actions to reduce recurrence, with owners and deadlines.

Templates

Incident Record (compact)

---
artifact: Incident Record
id: INC-<system>-<date>-<number>
incident_type: <Type: system, data, integration, user error>
severity: <P1 / P2 / P3 / P4>
affected_system: <System name and component>
detection_time: YYYY-MM-DD HH:MM
resolution_time: YYYY-MM-DD HH:MM
mttr: <Minutes or hours&gt
doc_author: <Name&gt
doc_reviewer: <Name&gt
doc_status: draft | reviewed | closed
---

## Symptom
- What was observed: <Error message, status, behavior>
- Who reported it: <User, system, monitor>
- Business impact: <What was affected and how>

## Timeline
| Time | Event | What was known | Action taken |
|------|-------|----------------|--------------|
| HH:MM | <Detection> | <What was known> | <What was done> |
| HH:MM | <Diagnosis> | <What was discovered> | <What was done> |
| HH:MM | <Resolution> | <What was fixed> | <What was done> |

## Diagnosis
- Systems checked: <Transactions, tools, logs used>
- Findings: <What was found>
- Leading hypothesis: <Most likely cause>

## Failed Attempts
| Attempt | Reason it was tried | Result |
|---------|---------------------|--------|
| <Action> | <Why> | <Outcome> |

## Resolution
- Action taken: <Exact fix>
- Verification: <How we confirmed it worked>
- Temporary or permanent: <Workaround or fix>

## Root Cause (if known)
- Cause: <What fundamentally went wrong>
- Evidence: <Log, trace, or data that confirms it>
- If unknown: <State unknown and leading hypothesis>

## Prevention Plan
| Action | Owner | Deadline | Status |
|--------|-------|----------|--------|
| <Prevention action> | <Name> | YYYY-MM-DD | <open | done> |

## Related Incidents
- <Link to previous incident records with similar symptoms>

Quality checklist

The symptom is specific enough that the next responder can search for it in the knowledge base.
The timeline includes timestamps and distinguishes known facts from later discoveries.
Failed attempts are documented to prevent repeated dead ends.
The resolution describes the exact action, not a generic summary.
The root cause is stated or explicitly marked as unknown.
The prevention plan has an owner, a deadline, and a verifiable action.
The record is reviewed by the responder and the incident review team.
The record is stored in a searchable location with tags for system, symptom, and component.

Common mistakes

Writing a ticket closure summary instead of an incident record. Consequence: the record says "fixed, closed" with no detail. The next responder has no starting point.
Guessing the root cause when it is unknown. Consequence: the organization invests in fixing the wrong problem. The real root cause continues to cause incidents.
Omitting failed attempts. Consequence: future responders waste time trying the same unsuccessful actions. The incident record is incomplete.
Writing the record days or weeks after the incident. Consequence: memory fades, details are lost, and the timeline becomes inaccurate.
Skipping the prevention plan. Consequence: the incident recurs because nothing was changed. The organization pays for the same failure repeatedly.

Weak output vs Strong output

Weak output

A ticket closure note: "IDoc failed with status 51. Checked mapping and found missing field. Updated mapping in PI. Reprocessed IDoc. Issue resolved. Ticket closed." No timeline, no error text, no system details, no failed attempts, no root cause, no prevention plan. When the same IDoc fails two weeks later, the new responder starts from zero.

Why it fails: The record is too thin to be useful for pattern analysis or future response. It does not help the next responder, it does not reveal recurrence patterns, and it provides no evidence for improvement.

Strong output

---
artifact: Incident Record
id: INC-PI-2026-06-10-001
incident_type: integration
severity: P2
affected_system: SAP PI / S/4HANA Sales Order Processing
detection_time: 2026-06-10 08:15
resolution_time: 2026-06-10 10:45
mttr: 2h 30m
doc_author: M. Chen
doc_reviewer: T. Nguyen
doc_status: closed
---

## Symptom
- What was observed: Sales order IDoc type ORDERS05 failed in WE02 with status 51. Error text: "Delivery block for plant 1002 not found in mapping table."
- Who reported it: EDI monitoring alert at 08:15, followed by customer service escalation at 08:30.
- Business impact: 12 sales orders blocked for plant 1002. Customer service manually creating orders in VA01 as workaround.

## Timeline
| Time | Event | What was known | Action taken |
|------|-------|----------------|--------------|
| 08:15 | Monitoring alert fires | Status 51 on ORDERS05 for plant 1002 | Checked WE02 for error details |
| 08:25 | Error text confirmed | "Delivery block not found in mapping table" | Checked SAP PI mapping for plant 1002 |
| 08:40 | Mapping gap identified | Plant 1002 added last week; mapping not updated | Attempted to add plant 1002 to mapping table (failed — table locked) |
| 09:00 | Basis team engaged | Table locked by background job | Basis team terminated background job, released table lock |
| 09:30 | Mapping updated | Plant 1002 delivery block added to mapping | Tested with one IDoc — processed successfully |
| 10:00 | Batch reprocessing | 12 affected IDocs identified | Reprocessed all 12 IDocs via WE19 |
| 10:45 | Verification complete | All orders created in S/4, no errors | Confirmed with customer service that manual entry can stop |

## Failed Attempts
| Attempt | Reason it was tried | Result |
|---------|---------------------|--------|
| Add plant 1002 to mapping table immediately | Direct fix seemed possible | Failed because table was locked by background job |
| Reprocess IDoc without fixing mapping | Thought error was transient | Failed with same status 51, error text unchanged |

## Resolution
- Action taken: Updated SAP PI mapping table ZDLV_BLOCK_MAP to include delivery block "01" for plant 1002. Reprocessed 12 failed IDocs via WE19.
- Verification: All 12 IDocs processed with status 53. Sales orders created in VA01. Customer service confirmed.
- Temporary or permanent: Permanent fix. Table lock issue was one-time background job conflict.

## Root Cause
- Cause: Plant 1002 was added to the organizational model on 2026-06-05 but the PI mapping table was not updated. The change process for new plants does not include a PI mapping checklist.
- Evidence: Change record CHG-2026-045 (plant 1002 creation) with no PI mapping task. Mapping table ZDLV_BLOCK_MAP last updated 2026-05-01.

## Prevention Plan
| Action | Owner | Deadline | Status |
|--------|-------|----------|--------|
| Add PI mapping checklist to plant creation change request | S. Mueller | 2026-06-20 | open |
| Create alert for IDoc status 51 with "delivery block not found" error | T. Nguyen | 2026-06-25 | open |
| Review all plants added since 2026-01-01 for PI mapping completeness | M. Chen | 2026-06-18 | open |

## Related Incidents
- INC-PI-2026-05-15-003: Similar mapping missing for plant 1001 (different field, same root cause).

Agent instructions

AI Prompt Pattern

Role: Incident documentation writer for SAP operational support.

Context: You have a resolved incident ticket, responder notes, and system logs. You need to produce an Incident Record that captures the full response narrative for future responders and pattern analysis.

Task: Create a structured Incident Record using the template below. Include a timeline, specific symptoms, failed attempts, exact resolution, root cause, and prevention plan.

Output format: Structured Incident Record in Markdown with tables for timeline, failed attempts, and prevention plan.

Never guess the root cause. If the root cause is unknown, state "Unknown" and describe the leading hypothesis. Do not invent certainty.
Always document failed attempts. Future responders must know what was already tried and why it did not work.
Always describe the exact resolution. Include transaction codes, program names, parameter values, and verification steps. "Fixed mapping" is not enough.
Always include a prevention plan with an owner and a deadline. If no prevention is possible, state why.
Write the timeline with timestamps. Distinguish what was known at each point from what was discovered later.
Link to related incidents. If the same symptom or root cause has appeared before, reference the previous record. This makes patterns visible.
Do not include sensitive data. Use anonymized IDs, not real customer names, account numbers, or personal data.
Link to Atlas diagnostics when the incident touches documented SAP failure modes. For example, IDoc incidents should reference SAP IDoc Status Diagnostics.

Related skills

Incident Triage Working Skill — Use to classify and route incidents before they are documented.
Root Cause Analysis Working Skill — Use to perform deep cause analysis before writing the root cause section of the incident record.
Runbook Writing Working Skill — Use to document the resolution steps as a reusable operational procedure.
Knowledge Article Writing Working Skill — Use to convert incident records into self-service knowledge articles for common issues.
Recurring Ticket Pattern Analysis Working Skill — Use to analyze incident records for patterns and systemic issues.

Related Atlas pages

SAP IDoc Status Diagnostics — Diagnostic context for IDoc-related incidents.
SAP Background Job Diagnostics — Diagnostic context for background job incidents.
SAP Interface Monitoring Diagnostics — Monitoring context for integration incidents.
SAP Integration Error Handling Diagnostics — Error handling context for multi-system incidents.

Verification status and limitations

This skill is a public working interpretation of incident documentation practices. It is not official ITIL, SAP, or ISO documentation. It focuses on operational incident records in enterprise and SAP environments where incidents are frequent, responders rotate, and pattern visibility is essential for improvement.

Known limitations: the skill does not cover incident response procedures, escalation protocols, or communication management during an incident. It assumes the incident is resolved and the task is to document it. It does not replace formal post-mortem facilitation or blameless post-mortem culture frameworks. It does not cover security incident documentation, which may have classification and handling requirements beyond this template.