Skip to content

Gap Analysis

Use this skill to compare a codebase against a defined target state and produce a structured, evidence-based gap report with prioritised remediation actions.

Problem

Teams need to understand where a codebase stands relative to a target operational standard before investing in remediation. Without a structured comparison, gaps are discovered ad hoc, priorities are unclear, and effort estimates are unreliable.

This skill produces a gap analysis that:

  • compares every relevant dimension systematically rather than checking only the obvious surfaces
  • distinguishes where the codebase is ahead, aligned, or behind the target
  • ranks gaps by deployment criticality (P0 → P3)
  • identifies key decisions that block remediation planning

When To Use It

  • A prototype or external codebase needs assessment against team/org operational standards.
  • A modernisation initiative requires a baseline inventory of what exists and what's missing.
  • A new service is being onboarded and needs to meet deployment, observability, auth, and CI/CD requirements.
  • The user asks for a "readiness assessment", "gap analysis", "maturity review", or "standards comparison".

Workflow

  1. Define the target state. Read any existing standards documents, deployment strategies, or reference implementations. If none exist, interview the user to establish the target baseline. Use references/analysis-dimensions.md as the dimension checklist.

  2. Inventory the codebase. Explore the repository structure thoroughly. Use subagents for large repos. Gather:

  3. Technology stack (language version, frameworks, package manager, lockfiles)
  4. Architecture patterns (monolith vs microservice, domain boundaries, storage layer)
  5. CI/CD configuration (platform, stages, gates, deployment targets)
  6. Containerisation (Dockerfiles, registries, infrastructure-as-code)
  7. Observability (telemetry SDK, logging, metrics, tracing)
  8. Authentication and authorisation model
  9. Testing strategy (coverage thresholds, test categories, e2e capability)
  10. Security tooling (secret scanning, dependency audit, SAST)
  11. Documentation (ADRs, runbooks, developer guides, OpenAPI specs)

  12. Operational readiness (change management, rollback, incident response)

  13. Compare dimension by dimension. For each dimension in references/analysis-dimensions.md:

  14. State the target standard with concrete detail
  15. State the current state with evidence (file paths, config values, presence/absence)
  16. Classify as: ✅ Aligned, ⚠️ Different but acceptable, or ❌ Gap

  17. Note where the codebase exceeds the target — these are cross-pollination opportunities

  18. Rank gaps by priority. Use references/priority-framework.md:

  19. P0 — Required for initial deployment (blockers)
  20. P1 — Required for production promotion (tst/prd gates)
  21. P2 — Required for operational maturity

  22. P3 — Nice to have / cross-pollination opportunities

  23. Identify key decisions. List decisions that must be made before remediation can proceed. For each, state the options, trade-offs, and a recommendation.

  24. Produce the report. Use references/gap-report-template.md for the output structure.

Branching Rules

  • If the user provides a specific target state document, use it as the primary reference. Do not invent additional standards.
  • If no target state exists, use references/analysis-dimensions.md as a generic baseline and ask the user to confirm scope.
  • If the codebase is a prototype, do not penalise missing operational layers — flag them as gaps with appropriate priority but acknowledge they are expected.
  • If the codebase exceeds the target in some dimensions, document these as strengths to preserve and cross-pollination opportunities.
  • If the analysis spans too many dimensions for a single pass, split into focused sub-analyses (e.g., "CI/CD gap analysis", "security gap analysis") and produce a summary.

Execution Rules

  • Ground every finding in evidence: file paths, config values, presence/absence of specific files or patterns. Do not make claims without proof.
  • Use tables for dimension-by-dimension comparison — they are easier to scan than prose.
  • Distinguish between "gap" (missing relative to target) and "different" (alternative approach that achieves the same goal). Not every difference is a gap.
  • Include effort estimates (Trivial / Small / Medium / Large) for each gap to enable planning. Use the wall-clock T-shirt scale from effort-scales.yaml and remediation-plan task sizing.
  • Document architecture strengths that must be preserved during remediation — avoid plans that would regress quality.
  • Keep the executive summary to 3–5 sentences. Detail belongs in the dimension tables.

References

Required Output

  • Executive summary (3–5 sentences).
  • Technology stack comparison table.
  • Architecture and design quality assessment (ahead / aligned / behind).
  • Dimension-by-dimension gap tables with evidence.
  • Overall assessment scorecard (rated dimensions).
  • Priority actions table (P0–P3) with effort estimates.
  • Key decisions required (with options and recommendations).
  • Cross-pollination opportunities (if applicable).

Troubleshooting

Error: Report lists too many gaps with no clear priority. Cause: All dimensions were assessed at equal depth without priority ranking. Solution: Apply the priority framework (P0–P3) from references/priority-framework.md. Rank by deployment criticality, not severity alone.

Error: Findings lack evidence — claims are unsubstantiated. Cause: Codebase exploration was too shallow (e.g. only checked top-level files). Solution: Use subagents for deep exploration. Every gap claim must cite a file path, config value, or confirmed absence.

Error: Everything is marked as a gap — no strengths documented. Cause: Analysis only looked for negatives, not areas where the codebase meets or exceeds the target. Solution: Explicitly check for ✅ Aligned and 🟢 Ahead classifications. A balanced report builds trust.

Completion Bar

  • Every dimension in scope is assessed or explicitly marked out of scope.
  • Every gap claim has concrete evidence (file path, config absence, etc.).
  • Gaps are prioritised by deployment criticality, not just severity.
  • Strengths are documented alongside gaps — the report is balanced.
  • Key decisions are identified with options and recommendations.
  • The report is actionable: a reader can create Issue/Jira tickets directly from the priority tables.