event4u-app project-analysis-hypothesis-driven
When to use
Use this skill when:
- There is a concrete issue to explain
- Multiple root causes are plausible
- The system spans several layers
- A shallow single-explanation answer would be risky
universal-project-analysisorbug-analyzerroutes here
Do NOT use when:
- You are still discovering the stack and architecture
- The issue is already proven and only needs implementation
- The request is a broad project overview without a specific problem focus
Core principles
- Never stop at the first plausible explanation
- Code, docs, and evidence beat intuition
- Rejected hypotheses matter
- Multiple interacting causes are common
- Uncertainty must be marked explicitly
Procedure
1. Define the observed problem
State clearly: what happens, where it happens, when it happens, what was expected instead.
Use concrete evidence: errors, stack traces, behavior differences, failing tests, logs.
2. Build the hypothesis tree
Generate multiple competing explanations.
Typical categories:
- config issue
- version mismatch
- package misuse
- async/timing issue
- data inconsistency
- architecture flaw
Do not stop at one explanation.
3. Prioritize hypotheses
Rank by: likelihood, impact, testability. Start with the most testable high-value explanation.
4. Validate each hypothesis
For each hypothesis:
- check code
- check docs
- check runtime evidence
- check real-world reports if relevant
Mark: ✅ confirmed, ❌ rejected, ❓ uncertain.
5. Check system interactions
Look for cross-system causes:
| System A | ↔ | System B | What can go wrong |
|---|---|---|---|
| Framework | ↔ | Package | Version mismatch, wrong lifecycle hook, config conflict |
| Sync code | ↔ | Async code | Lost context, stale data, race conditions |
| Config | ↔ | Runtime | Cached config doesn't match env |
| Cache | ↔ | Database | Stale reads, inconsistent state after write |
| Auth | ↔ | Middleware | Order-dependent behavior, missing guards |
| Events | ↔ | Jobs | Events fire during seeding, serialization issues |
| Transaction | ↔ | External calls | Side effects can't be rolled back |
6. Perform reality check
Ask:
- does this fully explain the behavior?
- what remains unexplained?
- could multiple causes interact?
- does contradictory evidence exist?
If anything major remains unexplained: continue analysis, do not present a final conclusion yet.
7. Validate conclusion quality
Check:
- at least 2 plausible hypotheses were considered where appropriate
- rejected hypotheses are documented
- conclusion is backed by code/doc/runtime evidence
- confidence level is explicit
- partial explanations are not presented as complete
Output format
- Problem statement
- Hypothesis tree
- Confirmed findings
- Rejected hypotheses
- Remaining uncertainties
- Root-cause conclusion
- Confidence level
- Recommended next steps
Gotcha
- The model tends to lock onto the first plausible explanation too early.
- Contradictory evidence usually means the current conclusion is wrong or incomplete.
- Many production issues are caused by multiple interacting factors, not one neat bug.
Do NOT
- Do NOT present guesses as facts
- Do NOT skip rejected hypotheses
- Do NOT stop after one plausible explanation
- Do NOT ignore version-specific or package-specific behavior
- Do NOT claim full root cause if meaningful uncertainty remains