Skip to content

im-shashanks/claude-plugins / shaktra/skills/shaktra-analyze

shaktra-analyze

Verified

Codebase Analyzer workflow for brownfield codebases — deep structural analysis producing structured YAML artifacts for downstream agents. Use this skill whenever the user wants to analyze, assess, or understand an existing codebase — including requests like "analyze my codebase", "what's the health of this project", "check for tech debt", "audit dependencies", "understand this codebase before we start", or any brownfield due diligence task.

FileKindSize
SKILL.mdskill md13.4 KB
analysis-dimensions-core.mdmarkdown14.2 KB
analysis-dimensions-git.mdmarkdown5.5 KB
analysis-dimensions-health.mdmarkdown12.7 KB
analysis-output-schemas.mdmarkdown9.2 KB
debt-strategy.mdmarkdown5.7 KB
deep-analysis-workflow.mdmarkdown13.2 KB
dependency-audit.mdmarkdown6.1 KB
standard-analysis-workflow.mdmarkdown7.2 KB

analysis-dimensions-health.md

View on GitHub
# Analysis Dimensions — Health (D5-D8)

Dimensions that answer "How HEALTHY is this codebase?" — its dependencies, debt, data flows, and risk areas.

**Used by:** shaktra-cba-analyzer agent during `/shaktra:analyze` workflow.
**Input dependency:** All dimensions consume `static.yml` (ground truth) and `overview.yml` (project context).
**Companion:** `analysis-dimensions-core.md` defines D1-D4, `analysis-dimensions-git.md` defines D9.

---

## D5: Dependencies & Tech Stack → `dependencies.yml`

**Scope:** All project dependencies, their health, version currency, and potential risks.
**Downstream impact:** The dependency-audit workflow transforms these findings into upgrade stories. The architect uses dependency health to assess feasibility of design decisions that rely on specific libraries.

**What to analyze:**
1. **Direct dependencies** — name, version, purpose, last updated, license
2. **Transitive dependencies** — significant transitive deps that affect the project
3. **Dependency health** — maintenance status (active, maintenance-only, abandoned, archived)
4. **Version currency** — current vs latest, major version gaps
5. **Known vulnerabilities** — check for known CVEs via package manager audit commands
6. **Dependency overlap** — multiple libraries serving the same purpose

**Evidence requirements:**
- Versions from actual lockfile/manifest, not guessed
- Health status based on recent commit activity, issue responsiveness
- CVE data from `npm audit`, `pip audit`, `cargo audit`, or equivalent

**Output structure:**
```yaml
summary: |
  {Self-contained 300-token overview: total deps, health distribution,
   critical CVEs, notable risks}
details:
  direct:
    - name: string
      version: string
      purpose: string
      health: active | maintenance | abandoned | archived
      latest_version: string
      license: string
  transitive_notable:
    - name: string
      pulled_by: string
      risk: string
  vulnerabilities:
    - package: string
      severity: critical | high | medium | low
      cve: string
      description: string
  overlaps:
    - purpose: string
      libraries: [string]
      recommendation: string
```

**Self-check before writing:**
- Versions come from actual lockfile/manifest content — not from memory or guesses
- Every dependency has a `purpose` field explaining why the project uses it
- Summary includes total dependency count, health distribution, and any critical CVEs

---

## D6: Technical Debt & Security → `tech-debt.yml`

**Scope:** Code quality issues, technical debt indicators, security posture, and an overall health score.
**Downstream impact:** The debt-strategy workflow transforms these findings into prioritized remediation stories. The sw-quality agent uses the health score as a baseline. The cross-cutting risk correlation (D8) combines debt data with critical paths to identify the highest-risk files in the codebase.

**What to analyze:**
1. **Debt indicators** — TODO/FIXME/HACK counts with context, dead code, unused imports, disabled tests, commented-out code blocks
2. **Complexity hotspots** — files/functions with high cyclomatic complexity, deeply nested logic, long functions/methods. Produce quantitative metrics: total files/lines, avg/max function length, avg/max file length, nesting depth counts, test-to-source ratio.
3. **Test health** — test-to-source ratio, test coverage gaps (modules with no tests), flaky test indicators
4. **Security posture** — hardcoded secrets, SQL injection risks, XSS vectors, insecure dependencies, missing auth on endpoints, overly permissive CORS
5. **Health score** — aggregate 1-10 score based on debt density, test coverage, security issues, code consistency

**Evidence requirements:**
- Debt indicators cite specific files and line numbers
- Complexity metrics based on actual code analysis (nesting depth, function length)
- Security findings cite specific code patterns, not theoretical risks

**Output structure:**
```yaml
summary: |
  {Self-contained 400-token overview: health score, debt density,
   critical security issues, test coverage status}
details:
  health_score: integer  # 1-10
  health_breakdown:
    code_quality: integer
    test_coverage: integer
    security: integer
    consistency: integer
  debt:
    todo_count: integer
    fixme_count: integer
    hack_count: integer
    dead_code_files: [string]
    disabled_tests: [string]
    hotspots:
      - file: string
        issue: string  # high complexity, deep nesting, long function
        metric: string
  security:
    - category: string
      severity: critical | high | medium | low
      location: string
      description: string
      remediation: string
  test_health:
    test_to_source_ratio: string
    untested_modules: [string]
    coverage_estimate: string
  quantitative_metrics:
    total_source_files: integer
    total_source_lines: integer
    avg_function_length: integer
    max_function_length: {file: string, function: string, lines: integer}
    avg_file_length: integer
    max_file_length: {file: string, lines: integer}
    deeply_nested_functions: integer
    long_functions: integer
    test_to_source_ratio: float
    files_without_tests: integer
    percent_files_tested: float
```

**Self-check before writing:**
- Debt indicators cite specific files and line numbers — not just counts without locations
- Complexity metrics (function length, nesting depth) are measured from actual code, not estimated
- Security findings reference specific code patterns in specific files — not theoretical risks that "could" exist
- Health score breakdown has non-zero values in all 4 categories (code_quality, test_coverage, security, consistency)
- `quantitative_metrics` section is fully populated with actual measurements

---

## D7: Data Flows & Integration → `data-flows.yml`

**Scope:** How data moves through the system, integration points with external services, and critically: integration gotchas that cause production incidents.
**Downstream impact:** The bug diagnostician uses data flows to trace issues across service boundaries. The sw-engineer uses integration point details to write correct mocks and integration tests. The architect uses flow criticality tiers to prioritize design decisions.

**What to analyze:**
1. **Data flows** — trace data from entry point through processing to storage/response. Classify each flow by criticality:
   - **Critical:** Revenue-impacting, data-loss-risking (payment, order, user creation)
   - **Important:** Feature-impacting (search, notification, reporting)
   - **Reference:** Supporting flows (logging, metrics, health checks)
2. **Integration points** — all external service connections: APIs, databases, queues, caches, file systems, third-party services
3. **Integration gotchas** — the non-obvious failure modes that cause production incidents:
   - Race conditions (concurrent writes to same resource)
   - TOCTOU bugs (check-then-act with stale data)
   - Webhook ordering issues (events arriving out of order)
   - Cache consistency problems (stale reads after writes)
   - Non-atomic multi-step operations (partial failure mid-sequence)
   - Timeout cascades (one slow service blocking the chain)
   - Retry storms (retries amplifying load during outages)

**Evidence requirements:**
- Data flows traced through actual code paths, not architecture diagrams
- Integration points verified via connection config, client instantiation
- Gotchas cite specific code patterns where the risk exists

**Output structure:**
```yaml
summary: |
  {Self-contained 500-token overview: flow count by tier,
   integration points, critical gotchas}
details:
  flows:
    - name: string
      tier: critical | important | reference
      entry_point: string
      path: [string]  # ordered list of file:function through the flow
      data_transforms: [string]
      storage: string
      risks: [string]
  integrations:
    - service: string
      type: api | database | queue | cache | filesystem | third_party
      connection: string  # config/env reference
      timeout: string | none
      retry: string | none
      circuit_breaker: string | none
  gotchas:
    - type: race_condition | toctou | webhook_ordering | cache_consistency | non_atomic | timeout_cascade | retry_storm
      location: string
      description: string
      impact: string
      current_mitigation: string | none
```

**Self-check before writing:**
- Data flows are traced through actual code paths — each step in `path:` references a real file:function
- Integration points verified via actual connection config or client instantiation in code
- Gotchas cite specific code locations where the risk pattern exists — not theoretical possibilities
- Flows are classified by criticality tier with justification

---

## D8: Critical Paths & Risk → `critical-paths.yml`

**Scope:** Code paths that require extra caution — revenue-critical, security-sensitive, performance-critical, and data-integrity code. Includes blast radius assessment and lessons learned from the codebase's history.
**Downstream impact:** The sw-quality agent uses the change risk index to calibrate review depth — high-risk files get more scrutiny. The developer agent checks critical path membership before modifying files. The cross-cutting risk section (combining D6, D8, D9) is the single most important risk signal for the entire framework.

**What to analyze:**
1. **Critical path identification** — classify code areas by risk category:
   - **Revenue-critical:** Payment processing, billing, subscription management, order fulfillment
   - **Security-sensitive:** Authentication, authorization, encryption, PII handling, secret management
   - **Performance-critical:** Hot paths under load, real-time processing, bulk operations
   - **Data-integrity:** Migration paths, schema changes, data transformations, backup/restore
2. **Blast radius assessment** — for each critical path, what breaks if it fails? How many users affected? Is the failure contained or cascading?
3. **Lessons learned from history** — evidence of past issues discovered from:
   - Git history: files with frequent bug-fix commits (many `fix:` prefixed commits)
   - Code comments: warnings, workarounds, known limitations
   - Error handling: defensive code suggesting past incidents
   - Test edge cases: regression tests suggesting past bugs
4. **Change risk index** — which files/modules require the most caution when modifying? Based on: criticality, complexity, coupling, historical bug density.
5. **Cross-cutting risk** — combine critical path membership, tech debt, test coverage, git change frequency, and coupling into a composite risk score per file. Requires reading `tech-debt.yml` (D6 output) and `git-intelligence.yml` (D9 output, if available). Reference the source dimension for each risk factor.

**Evidence requirements:**
- Critical paths traced to actual code locations, not theoretical
- Blast radius derived from dependency graph (who calls this code?)
- Lessons learned cite specific commits, comments, or test names
- Change risk index based on measurable factors
- Cross-cutting risk: reference source dimension for each risk factor

**Output structure:**
```yaml
summary: |
  {Self-contained 500-token overview: critical path count by category,
   highest-risk areas, key lessons learned}
details:
  critical_paths:
    - name: string
      category: revenue | security | performance | data_integrity
      files: [string]
      blast_radius:
        scope: contained | service | cross_service | user_facing
        affected: string
      current_protections: [string]
  lessons_learned:
    - source: git_history | code_comment | error_handling | regression_test
      location: string
      lesson: string
      implication: string  # what this means for future changes
  change_risk_index:
    - file: string
      risk: high | medium | low
      factors: [string]  # criticality, complexity, coupling, bug_density
      recommendation: string
  cross_cutting_risk:
    - file: string
      risk_factors:
        on_critical_path: boolean
        categories: [string]
        tech_debt_present: boolean
        debt_items: [string]
        test_coverage: none | partial | adequate
        change_frequency: high | medium | low
        coupling_score: high | medium | low
      composite_risk: critical | high | medium | low
      recommendation: string
```

**Self-check before writing:**
- Critical paths trace to actual code locations — not inferred from module names
- Blast radius derived from the dependency graph (who calls this code?) — not guessed
- Lessons learned cite specific commits, comments, or test names as evidence
- Change risk index factors are measurable and referenced — not subjective opinions
- Cross-cutting risk section references source dimension for each factor (D6 for debt, D9 for change frequency)
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall