SuperAPI AI Directory

problem-resolution-flow

General & other

View repository

Updated 10-16 02:31

About this skill

Problem Resolution Flow

Core Principle

Every fix must be traceable back to evidence. Never patch the symptom. If the same symptom is fixed three times, stop and question the design.

The Flow

① LOCATE     — evidence first: error message → logs → reproduced behavior → which component
② TRACE      — follow the data/call chain back to the original trigger (root-cause-tracing)
③ SEVERITY   — grade impact × urgency NOW (grading table) — P0/P1 → stop-and-restore path,
               investigation depth can wait; P2/P3 → proceed in order
④ CLASSIFY   — problem type: single-point / logic error / interaction UX / design or architecture
⑤ SCOPE      — line / function / module / project → determines fix depth
⑥ DRAFT      — form your own solution before looking outward
⑦ RESEARCH   — external evidence by type (competitor behavior / user logs / official or academic
               docs); key claims cross-validated across 2+ independent channels
⑧ DECIDE     — workaround vs permanent fix (decision rules); a shipped workaround must
               keep a tracked permanent-fix item
⑨ FIX        — TDD: write a failing test first, then the minimum change
⑩ VERIFY     — run the verifier (a check that produces pass/fail); full regression stays green
⑪ CLOSE      — refill tickets / handoff deltas / write a no-blame one-line lesson;
               recurring symptoms become a tracked problem with a known-error note
               (reusable knowledge for the next occurrence)

P0/P1 fast path (the significance of placing triage first): ③ After grading, if it is P0/P1, immediately enter the stop-the-bleeding branch— first restore service via workaround/rollback, then come back to complete ④-⑧ (root cause investigation may be deferred); recovery ≠ closure (see Incident vs Problem).

Severity Grading (industry-aligned)

Level Meaning Response
P0 Blocks all users / data corruption / security incident Handle immediately, stop routine work; restore service first, then dig deeper; fix + verify + postmortem
P1 Primary path unavailable (core functionality down) Handle as soon as possible; workaround recovery takes priority, permanent fix follows up
P2 Secondary functionality impaired / experience noticeably degraded Handle routinely, fix as planned
P3 Minor flaw / edge case Can be queued, fixed with the release
  • Impact assessment is based onevidence(logs/reproduction/number of user reports), not on gut feeling.
  • Escalation path: if the impact expands during handling (more users/data risk) → escalate severity and inform stakeholders.
  • Incident vs Problem(ITIL semantics): P0/P1 areincidents—restore service first (rollback/flag/degradation), root cause investigation may be deferred; root cause governance is aproblem—recovery does not equal closure, and the problem ticket must continue until a permanent fix or adjudication.

Rules

  • No fix without location. If you cannot say which component and which flow step fails, you are not ready to fix.
  • 3 strikes = upgrade. Fixing the same symptom 3+ times means the problem is one level up: single-point → module → design. Stop and question the architecture — and when you do, look for systemic factors (environment/process/tooling), not a single scapegoat "root cause" (complex failures are usually multi-factor).
  • Scope discipline. Fix at the scope the type demands — no bigger, no smaller. A single-point bug gets a line fix, not a refactor.
  • Draft before research. Think first; research validates or refutes, it does not replace thinking.
  • Research is not optional for UX problems. Interaction/design gaps need competitor comparison + user-log evidence, not just code reading.
  • Dual-channel verification. Key external claims must match across 2+ independent search channels; conflicting channels are the most valuable signal — dig.
  • Workaround is a state, not an exit. A workaround restores service; the permanent fix keeps a tracked item (ticket/audit item) until shipped and verified.
  • Ship with a test. The fix is not done until the failing test passes and the suite stays green (verification-before-completion).
  • Recovery over blame. When service is down, restore first, investigate depth second; post-incident, write a no-blame lesson (one line into the handoff/decision log) — blame kills the lesson, and the lesson is the product.

Workaround vs Permanent Fix (decision table)

Situation Decision
P0/P1, root cause unknown Restore via workaround first (rollback/feature flag/degradation path), root cause investigation continues
Root cause known but fix risk is high (large change/wide impact) workaround + permanent fix scheduled (tracking item must be created)
Root cause known, fix is small and testable Fix permanently directly (TDD)
3rd workaround for the same symptom Stop the workaround—escalate to a design/system problem (3 strikes rule)

Release control: the fix must pass this skill's VERIFY before merging; release/rollout (canary, flag switching, production change) is a separate decision—before the change, confirm there is a rollback plan (what changed can be reverted, what the rollback command is).

Anti-patterns

  • Patching the symptom and declaring done
  • Skipping classification and scope ("just fix it")
  • Single-channel research conclusions
  • Fixing beyond the scope (refactoring while fixing a typo)
  • No regression check before closing
  • Workaround without a tracked permanent fix
  • Restoring service and calling it done (incident closed, problem still open)
  • Blame in post-incident write-ups (kills the lesson)
  • Deploying a fix with no rollback plan

Relationship to sibling skills

  • problem-dive — intake methodology when a problem/UX complaint arrives: evidence first, do not start fixing. This skill takes over once the problem is understood and a fix path is chosen.
  • systematic-debugging — code root-cause investigation (observe → hypothesize → test → fix) for the code-bug path inside ①-③. Use both: systematic-debugging for root cause, this skill for the end-to-end flow.
  • audit-item — tracked permanent fixes / follow-ups land as audit items so gates can enumerate them.

Methodology Sources (2026-08 research)

  • SRE incident lifecycle (detect→respond→remediate→recover→learn) and blameless postmortem: Google SRE Book (sre.google/sre-book/postmortem-culture)
  • ITIL 4: incident vs problem, major incident path (Atlassian ITSM documentation)
  • Severity grading: industry P0-P3 convention; IEEE 1044 defect severity/priority matrix
  • Cost-of-defects law: Boehm (fix cost grows exponentially with phase—the earlier the fix, the cheaper)
  • Fix quality: empirical research on regression defects introduced by fixes (arXiv 2207.01942)
  • Critical perspective on root cause: David Woods "root cause is a myth" (complex-system accidents are multi-causal); Hollnagel ETTO principle (erikhollnagel.com)—supports 3 strikes escalation to the system level and rejects scapegoating-style single root causes