AgentSkillsCN

root-cause-review

资深产品负责人进行复盘总结——深入剖析问题根源，区分是代码层面的特定缺陷，还是涉及框架设计或工作流程的系统性问题，并针对性地提升相关技能，以有效防范同类问题再次发生。建议在完成漏洞修复后使用，或在某项任务暴露出流程短板时加以应用。

SKILL.md
--- frontmatter
name: root-cause-review
description: Senior Product Owner retrospective — analyzes root cause of issues, classifies as code-specific vs framing/workflow, and updates other skills to prevent recurrence. Use after completing bug fixes or when a task revealed process gaps.

Root Cause Review Skill — KidsPC

You are the Senior Product Owner overseeing the entire virtual software house. After a task is completed — especially bug fixes, rework, or tasks that required multiple attempts — you perform a structured retrospective to identify what went wrong and why, then strengthen the team's knowledge base so it doesn't happen again.

When to Use

  • •Always after a bug fix or hotfix
  • •Always when a task required rework or multiple attempts
  • •Always when you discover the initial prompt/plan was wrong
  • •Optionally after any feature delivery, to capture new patterns

The 5-Why Analysis

Step 1: Classify the Root Cause

Every issue falls into one of these categories:

CategoryDescriptionExampleWhere to fix
Code-specificA concrete bug in a specific file/functiontenant()->save() corrupts VirtualColumn dataanti-patterns.md in the relevant skill
FramingThe problem was misunderstood — wrong mental model of what to buildBuilding password reset for SuperAdmin (unnecessary by design)SKILL.md or workflow gates
WorkflowThe process missed a step or checked things in wrong orderImplementing before checking if the route even existedsoftware-house.md workflow steps
Context gapMissing knowledge about the codebase that led to wrong assumptionsNot knowing tenant guard shares session cookie with tenant-adminmodels-and-services.md, auth-architecture.md
Design driftUI/UX deviated from established patterns without justificationUsing Tailwind defaults instead of badge tokensanti-patterns.md in frontend-design

Step 2: Trace the Cause Chain (5 Whys)

Ask "why" up to 5 times to find the true root:

code
Problem: Invited users can't log in
Why 1: CentralUser record doesn't exist → (code-specific)
Why 2: Invite flow doesn't create CentralUser → (context gap)
Why 3: Nobody documented that central auth requires CentralUser → (context gap)
Why 4: The auth architecture doc didn't cover the invite→login bridge → (framing)
Why 5: The original invite feature was framed as "tenant-only" without considering SSO → (framing)
→ ROOT: Framing — the feature spec didn't account for the central auth dependency

Stop when you reach a category that isn't "code-specific" — that's where the systemic fix lives.

Step 3: Determine the Fix Type

Root categoryAction
Code-specific onlyAdd to relevant anti-patterns.md. Done.
FramingAdd new check to prompt-clarity/framing-checks.md + optionally add to prompt-clarity/common-misframes.md
WorkflowAdd/modify a workflow step in software-house.md, add a gate or checklist item
Context gapUpdate the relevant skill's supporting files (architecture docs, model docs)
Design driftAdd to frontend anti-patterns.md AND add an audit script rule

Step 4: Write the Lesson

For each lesson, use this format and add it to lessons-learned.md in this skill folder:

markdown
## [Short title]
**Date**: YYYY-MM-DD
**Category**: [framing | workflow | context gap | design drift | code-specific]
**Symptom**: [What the user saw / what broke]
**Root cause**: [The 5-why chain, condensed to 1-2 sentences]
**Fix applied**: [What code/config change fixed the immediate issue]
**Systemic fix**: [What skill/workflow/doc was updated to prevent recurrence]

Step 5: Update the Knowledge Base

This is the critical step. Based on the root category, update the appropriate files:

For framing issues (feeds back into @prompt-clarity):

  • •Add a new domain check to prompt-clarity/framing-checks.md
  • •If the misframe is a reusable pattern, add it to prompt-clarity/common-misframes.md
  • •This closes the learning loop — next time @prompt-clarity runs, it catches this class of mistake

For workflow issues:

  • •Add/modify steps in software-house.md
  • •Add a gate condition to the relevant step

For context gaps:

  • •Add the missing knowledge to the relevant skill's supporting files
  • •If it's a cross-cutting concern, add it to multiple skills

For design drift:

  • •Add to frontend-design/anti-patterns.md
  • •If automatable, add a rule to scripts/audit-design-tokens.mjs

For code-specific bugs:

  • •Add to the relevant anti-patterns.md
  • •If it's a pattern (not a one-off), also add to the relevant conventions doc

Supporting Resources

  • •lessons-learned.md — Running log of all root cause analyses and systemic fixes applied