📦 deps(skills): sync thirdparty skills
This commit is contained in:
ci[bot]
+266
@@ -0,0 +1,266 @@
|
||||
---
|
||||
name: codebase-recon
|
||||
description: This skill should be used when analyzing codebases, understanding architecture, or when "analyze", "investigate", "explore code", or "understand architecture" are mentioned.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Codebase Analysis
|
||||
|
||||
Evidence-based investigation → findings → confidence-tracked conclusions.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Gather evidence from multiple sources (code, docs, tests, history)
|
||||
2. Track confidence level as investigation progresses
|
||||
3. Based on findings:
|
||||
- If pattern analysis needed → load the `outfitter:patterns` skill
|
||||
- If root cause investigation → load the `outfitter:find-root-causes` skill
|
||||
- If ready to report → load the `outfitter:report-findings` skill
|
||||
4. Deliver findings with confidence level and caveats
|
||||
|
||||
<when_to_use>
|
||||
|
||||
- Codebase exploration and understanding
|
||||
- Architecture analysis and mapping
|
||||
- Pattern extraction and recognition
|
||||
- Technical research within code
|
||||
- Performance or security analysis
|
||||
|
||||
NOT for: wild guessing, assumptions without evidence, conclusions before investigation
|
||||
|
||||
</when_to_use>
|
||||
|
||||
<confidence>
|
||||
|
||||
| Bar | Lvl | Name | Action |
|
||||
|-----|-----|------|--------|
|
||||
| `░░░░░` | 0 | Gathering | Collect initial evidence |
|
||||
| `▓░░░░` | 1 | Surveying | Broad scan, surface patterns |
|
||||
| `▓▓░░░` | 2 | Investigating | Deep dive, verify patterns |
|
||||
| `▓▓▓░░` | 3 | Analyzing | Cross-reference, fill gaps |
|
||||
| `▓▓▓▓░` | 4 | Synthesizing | Connect findings, high confidence |
|
||||
| `▓▓▓▓▓` | 5 | Concluded | Deliver findings |
|
||||
|
||||
*Calibration: 0=0–19%, 1=20–39%, 2=40–59%, 3=60–74%, 4=75–89%, 5=90–100%*
|
||||
|
||||
Start honest. Clear codebase + focused question → level 2–3. Vague or complex → level 0–1.
|
||||
|
||||
At level 4: "High confidence in findings. One more angle would reach full certainty. Continue or deliver now?"
|
||||
|
||||
Below level 5: include `△ Caveats` section.
|
||||
|
||||
</confidence>
|
||||
|
||||
<principles>
|
||||
|
||||
## Core Methodology
|
||||
|
||||
**Evidence over assumption** — investigate when you can, guess only when you must.
|
||||
|
||||
**Multi-source gathering** — code, docs, tests, history, web research, runtime behavior.
|
||||
|
||||
**Multiple angles** — examine from different perspectives before concluding.
|
||||
|
||||
**Document gaps** — flag uncertainty with △, track what's unknown.
|
||||
|
||||
**Show your work** — findings include supporting evidence, not just conclusions.
|
||||
|
||||
**Calibrate confidence** — distinguish fact from inference from assumption.
|
||||
|
||||
</principles>
|
||||
|
||||
<evidence_gathering>
|
||||
|
||||
## Source Priority
|
||||
|
||||
1. **Direct observation** — read code, run searches, examine files
|
||||
2. **Documentation** — official docs, inline comments, ADRs
|
||||
3. **Tests** — reveal intended behavior and edge cases
|
||||
4. **History** — git log, commit messages, PR discussions
|
||||
5. **External research** — library docs, Stack Overflow, RFCs
|
||||
6. **Inference** — logical deduction from available evidence
|
||||
7. **Assumption** — clearly flagged when other sources unavailable
|
||||
|
||||
## Investigation Patterns
|
||||
|
||||
**Start broad, then narrow:**
|
||||
- File tree → identify relevant areas
|
||||
- Search patterns → locate specific code
|
||||
- Code structure → understand without full content
|
||||
- Read targeted files → examine implementation
|
||||
- Cross-reference → verify understanding
|
||||
|
||||
**Layer evidence:**
|
||||
- What does the code do? (direct observation)
|
||||
- Why was it written this way? (history, comments)
|
||||
- How does it fit the system? (architecture, dependencies)
|
||||
- What are the edge cases? (tests, error handling)
|
||||
|
||||
**Follow the trail:**
|
||||
- Function calls → trace execution paths
|
||||
- Imports/exports → map dependencies
|
||||
- Test files → understand usage patterns
|
||||
- Error messages → reveal assumptions
|
||||
- Comments → capture historical context
|
||||
|
||||
</evidence_gathering>
|
||||
|
||||
<output_format>
|
||||
|
||||
## During Investigation
|
||||
|
||||
After each evidence-gathering step emit:
|
||||
|
||||
- **Confidence:** {BAR} {NAME}
|
||||
- **Found:** { key discoveries }
|
||||
- **Patterns:** { emerging themes }
|
||||
- **Gaps:** { what's still unclear }
|
||||
- **Next:** { investigation direction }
|
||||
|
||||
## At Delivery (Level 5)
|
||||
|
||||
### Findings
|
||||
|
||||
{ numbered list of discoveries with supporting evidence }
|
||||
|
||||
1. {FINDING} — evidence: {SOURCE}
|
||||
2. {FINDING} — evidence: {SOURCE}
|
||||
|
||||
### Patterns
|
||||
|
||||
{ recurring themes or structures identified }
|
||||
|
||||
### Implications
|
||||
|
||||
{ what findings mean for the question at hand }
|
||||
|
||||
### Confidence Assessment
|
||||
|
||||
Overall: {BAR} {PERCENTAGE}%
|
||||
|
||||
High confidence areas:
|
||||
- {AREA} — {REASON}
|
||||
|
||||
Lower confidence areas:
|
||||
- {AREA} — {REASON}
|
||||
|
||||
### Supporting Evidence
|
||||
|
||||
- Code: { file paths and line ranges }
|
||||
- Docs: { references }
|
||||
- Tests: { relevant test files }
|
||||
- History: { commit SHAs if relevant }
|
||||
- External: { URLs if applicable }
|
||||
|
||||
## Below Level 5
|
||||
|
||||
### △ Caveats
|
||||
|
||||
**Assumptions:**
|
||||
- {ASSUMPTION} — { why necessary, impact if wrong }
|
||||
|
||||
**Gaps:**
|
||||
- {GAP} — { what's missing, how to fill }
|
||||
|
||||
**Unknowns:**
|
||||
- {UNKNOWN} — { noted for future investigation }
|
||||
|
||||
</output_format>
|
||||
|
||||
<specialized_techniques>
|
||||
|
||||
Load skills for specialized analysis (see Steps section):
|
||||
|
||||
- **Pattern analysis** → `outfitter:patterns`
|
||||
- **Root cause investigation** → `outfitter:find-root-causes`
|
||||
- **Research synthesis** → `outfitter:report-findings`
|
||||
- **Architecture analysis** → see [architecture-analysis.md](references/architecture-analysis.md)
|
||||
|
||||
</specialized_techniques>
|
||||
|
||||
<workflow>
|
||||
|
||||
Loop: Gather → Analyze → Update Confidence → Next step
|
||||
|
||||
1. **Calibrate starting confidence** — what do we already know?
|
||||
2. **Identify evidence sources** — where can we look?
|
||||
3. **Gather systematically** — collect from multiple angles
|
||||
4. **Cross-reference findings** — verify patterns hold
|
||||
5. **Flag uncertainties** — mark gaps with △
|
||||
6. **Synthesize conclusions** — connect evidence to insights
|
||||
7. **Deliver with confidence level** — clear about certainty
|
||||
|
||||
At each step:
|
||||
- Document what you found (evidence)
|
||||
- Note what it means (interpretation)
|
||||
- Track what's still unclear (gaps)
|
||||
- Update confidence bar
|
||||
|
||||
</workflow>
|
||||
|
||||
<validation>
|
||||
|
||||
Before concluding (level 4+):
|
||||
|
||||
**Check evidence quality:**
|
||||
- ✓ Multiple sources confirm pattern?
|
||||
- ✓ Direct observation vs inference clearly marked?
|
||||
- ✓ Assumptions explicitly flagged?
|
||||
- ✓ Counter-examples considered?
|
||||
|
||||
**Check completeness:**
|
||||
- ✓ Original question fully addressed?
|
||||
- ✓ Edge cases explored?
|
||||
- ✓ Alternative explanations ruled out?
|
||||
- ✓ Known unknowns documented?
|
||||
|
||||
**Check deliverable:**
|
||||
- ✓ Findings supported by evidence?
|
||||
- ✓ Confidence calibrated honestly?
|
||||
- ✓ Caveats section included if <100%?
|
||||
- ✓ Next steps clear if incomplete?
|
||||
|
||||
</validation>
|
||||
|
||||
<rules>
|
||||
|
||||
ALWAYS:
|
||||
- Investigate before concluding
|
||||
- Cite evidence sources with file paths/URLs
|
||||
- Use confidence bars to track certainty
|
||||
- Flag assumptions and gaps with △
|
||||
- Cross-reference from multiple angles
|
||||
- Document investigation trail
|
||||
- Distinguish fact from inference
|
||||
- Include caveats below level 5
|
||||
|
||||
NEVER:
|
||||
- Guess when you can investigate
|
||||
- State assumptions as facts
|
||||
- Conclude from single source
|
||||
- Hide uncertainty or gaps
|
||||
- Skip validation checks
|
||||
- Deliver without confidence assessment
|
||||
- Conflate evidence with interpretation
|
||||
|
||||
</rules>
|
||||
|
||||
<references>
|
||||
|
||||
Core methodology:
|
||||
- [confidence.md](../pathfinding/references/confidence.md) — confidence calibration (shared with pathfinding)
|
||||
|
||||
Micro-skills (load as needed):
|
||||
- `outfitter:patterns` — extracting and validating patterns
|
||||
- `outfitter:find-root-causes` — systematic problem diagnosis
|
||||
- `outfitter:report-findings` — multi-source research synthesis
|
||||
|
||||
Local references:
|
||||
- [architecture-analysis.md](references/architecture-analysis.md) — system structure mapping
|
||||
|
||||
Related skills:
|
||||
- `outfitter:pathfinding` — clarifying requirements before analysis
|
||||
- `outfitter:debugging` — structured bug investigation
|
||||
|
||||
</references>
|
||||
@@ -0,0 +1,220 @@
|
||||
# Architecture Analysis
|
||||
|
||||
Techniques for analyzing system structure, dependencies, and component relationships.
|
||||
|
||||
## Dependency Mapping
|
||||
|
||||
### Forward Dependencies
|
||||
|
||||
What a component relies on:
|
||||
1. **Direct imports** — explicit dependencies in code
|
||||
2. **Indirect references** — called through interfaces
|
||||
3. **Runtime dependencies** — configuration, environment
|
||||
4. **Data dependencies** — shared state, databases
|
||||
|
||||
### Reverse Dependencies
|
||||
|
||||
What relies on this component:
|
||||
1. **Direct dependents** — explicit imports from other modules
|
||||
2. **Interface consumers** — components using this API
|
||||
3. **Side effect consumers** — code relying on mutations
|
||||
4. **Event subscribers** — listeners for this component's events
|
||||
|
||||
### Circular Dependencies
|
||||
|
||||
Red flags:
|
||||
- A imports B, B imports A
|
||||
- Longer cycles: A → B → C → A
|
||||
- Implicit cycles through shared state
|
||||
|
||||
Resolution strategies:
|
||||
- Extract shared code to separate module
|
||||
- Introduce interface/abstraction layer
|
||||
- Invert dependency direction
|
||||
- Break into smaller components
|
||||
|
||||
## Layer Identification
|
||||
|
||||
### Detecting Layers
|
||||
|
||||
Look for:
|
||||
- **Directional flow** — data/control flows one way
|
||||
- **Abstraction levels** — concrete → abstract as you ascend
|
||||
- **Responsibility clustering** — similar concerns grouped
|
||||
- **Interface boundaries** — clear contracts between groups
|
||||
|
||||
### Common Layer Patterns
|
||||
|
||||
**Three-tier**:
|
||||
- Presentation (UI, API endpoints)
|
||||
- Business logic (domain, workflows)
|
||||
- Data access (repositories, queries)
|
||||
|
||||
**Hexagonal/Clean**:
|
||||
- Core domain (entities, business rules)
|
||||
- Application layer (use cases, orchestration)
|
||||
- Infrastructure (frameworks, external services)
|
||||
- Interfaces (controllers, adapters)
|
||||
|
||||
**Microservices**:
|
||||
- Service boundary (API gateway)
|
||||
- Service logic (domain per service)
|
||||
- Data layer (per-service database)
|
||||
- Cross-cutting (auth, logging, monitoring)
|
||||
|
||||
### Layer Violations
|
||||
|
||||
Violations indicate architectural drift:
|
||||
- Lower layer imports higher layer
|
||||
- Business logic in presentation layer
|
||||
- Data access code in domain entities
|
||||
- Infrastructure concerns leaking into core
|
||||
|
||||
## Interface Analysis
|
||||
|
||||
### Contract Definition
|
||||
|
||||
Examine:
|
||||
- **Input types** — what does it accept?
|
||||
- **Output types** — what does it return?
|
||||
- **Error modes** — what can fail, how?
|
||||
- **Side effects** — mutations, I/O, state changes
|
||||
- **Invariants** — what must always be true?
|
||||
|
||||
### API Quality
|
||||
|
||||
Strong interfaces show:
|
||||
- **Cohesion** — methods belong together
|
||||
- **Minimal surface** — small, focused API
|
||||
- **Clear contracts** — types tell the story
|
||||
- **Stability** — changes don't cascade
|
||||
- **Composability** — works well with others
|
||||
|
||||
Weak interfaces show:
|
||||
- **Kitchen sink** — unrelated methods bundled
|
||||
- **Leaky abstractions** — implementation details exposed
|
||||
- **Unstable** — frequent breaking changes
|
||||
- **Rigid** — hard to extend or compose
|
||||
|
||||
## Component Relationships
|
||||
|
||||
### Relationship Types
|
||||
|
||||
**Composition**:
|
||||
- Component owns sub-components
|
||||
- Lifecycles coupled
|
||||
- Strong cohesion
|
||||
- Example: `Page` owns `Header`, `Footer`
|
||||
|
||||
**Aggregation**:
|
||||
- Component references others
|
||||
- Independent lifecycles
|
||||
- Loose coupling
|
||||
- Example: `ShoppingCart` references `Product`
|
||||
|
||||
**Dependency**:
|
||||
- Uses another component's interface
|
||||
- No ownership
|
||||
- Can be swapped
|
||||
- Example: `AuthService` uses `Database`
|
||||
|
||||
**Association**:
|
||||
- Knows about but doesn't own
|
||||
- Weak relationship
|
||||
- Often bidirectional
|
||||
- Example: `User` ↔ `Post` (many-to-many)
|
||||
|
||||
### Coupling Analysis
|
||||
|
||||
**Low coupling** (good):
|
||||
- Communicate through interfaces
|
||||
- Few shared assumptions
|
||||
- Changes localized
|
||||
- Easy to test in isolation
|
||||
|
||||
**High coupling** (risky):
|
||||
- Direct field access
|
||||
- Shared mutable state
|
||||
- Knowledge of implementation
|
||||
- Changes ripple widely
|
||||
|
||||
## Architectural Pattern Recognition
|
||||
|
||||
### Layered Architecture
|
||||
|
||||
Indicators:
|
||||
- Unidirectional dependencies (top → bottom)
|
||||
- Each layer uses only layer below
|
||||
- Clear separation of concerns
|
||||
|
||||
Trade-offs:
|
||||
- ✓ Simple, well-understood
|
||||
- ✓ Easy to enforce rules
|
||||
- ✗ Can become rigid
|
||||
- ✗ Performance overhead
|
||||
|
||||
### Event-Driven Architecture
|
||||
|
||||
Indicators:
|
||||
- Pub/sub or message queues
|
||||
- Decoupled components
|
||||
- Asynchronous communication
|
||||
- Event sourcing patterns
|
||||
|
||||
Trade-offs:
|
||||
- ✓ Scalable, resilient
|
||||
- ✓ Loose coupling
|
||||
- ✗ Harder to reason about flow
|
||||
- ✗ Eventual consistency challenges
|
||||
|
||||
### Microservices
|
||||
|
||||
Indicators:
|
||||
- Service per bounded context
|
||||
- Independent deployment
|
||||
- API-based communication
|
||||
- Decentralized data
|
||||
|
||||
Trade-offs:
|
||||
- ✓ Independent scaling
|
||||
- ✓ Technology diversity
|
||||
- ✗ Distributed system complexity
|
||||
- ✗ Operational overhead
|
||||
|
||||
## Analysis Workflow
|
||||
|
||||
### Top-Down
|
||||
|
||||
Start broad, narrow focus:
|
||||
1. **System boundaries** — what's in scope?
|
||||
2. **Major components** — high-level modules
|
||||
3. **Component interactions** — how they communicate
|
||||
4. **Internal structure** — zoom into each component
|
||||
5. **Implementation** — code-level details
|
||||
|
||||
### Bottom-Up
|
||||
|
||||
Start specific, build understanding:
|
||||
1. **Entry point** — main(), server start, UI root
|
||||
2. **Call graph** — trace execution paths
|
||||
3. **Cluster calls** — group related functionality
|
||||
4. **Extract components** — identify logical boundaries
|
||||
5. **Map relationships** — connect the pieces
|
||||
|
||||
### Targeted
|
||||
|
||||
Focus on specific concern:
|
||||
1. **Define question** — what are you trying to understand?
|
||||
2. **Identify relevant code** — where does this happen?
|
||||
3. **Trace dependencies** — what does it touch?
|
||||
4. **Analyze impact** — what would changing this affect?
|
||||
5. **Document findings** — capture insights
|
||||
|
||||
## Documentation Extraction
|
||||
|
||||
From architecture analysis, capture:
|
||||
- **Component diagram** — boxes and arrows
|
||||
- **Dependency graph** — what imports what
|
||||
- **Layer diagram** — abstraction levels
|
||||
- **Sequence diagrams** — interaction flows
|
||||
- **Decision records** — why this structure?
|
||||
Reference in New Issue
Block a user