Gap Analysis Phase 1: Finding Unimplemented Requirements

Step-by-step playbook for Phase 1 gap analysis: map acceptance criteria to code using hybrid retrieval. Outputs DONE, PARTIAL, MISSING with cited files. Find what you did not build.

What Phase 1 does

Phase 1 gap analysis answers one critical question: are all acceptance criteria actually implemented in the code?

It reads your acceptance criteria. It searches your codebase. It creates a mapping. For each criterion, it outputs one of three statuses:

• DONE: acceptance criterion is fully implemented; here are the files that implement it.

• PARTIAL: some parts are implemented, others are missing; here is what we found and what is missing.

• MISSING: no implementation found; this criterion is not in the code.

This is evidence. Not opinion.

How Phase 1 works: the mechanics

Phase 1 uses hybrid retrieval to match requirements to code. Here is the process:

Step 1: Extract acceptance criteria from requirements

Phase 1 reads your specification (BRD, PRD, user story acceptance criteria). It extracts each discrete criterion. Each criterion becomes a search target.

Example criteria:

• "Users can delete their account in account settings."

• "All personal data is purged within 30 days."

• "A confirmation email is sent to the email on file."

Step 2: Hybrid retrieval searches the codebase

For each criterion, Phase 1 performs hybrid retrieval. It does not just keyword match. It understands the semantic meaning of the criterion and searches for code that implements that meaning.

Hybrid retrieval combines:

• Keyword search: "delete", "account", "purge", "data"

• Semantic search: embeddings that understand "remove user data" and find code that does that

• Structure search: looks for API endpoints, database queries, and functions that fit the pattern

This finds code even if it uses different variable names or structures than the requirement.

Step 3: Expand one hop along the code graph

When hybrid retrieval finds relevant code, Phase 1 expands one hop along the code graph. It finds functions that call the matched code, and functions that are called by it.

Why? Because a single function rarely implements a full acceptance criterion. Usually:

• An API endpoint calls a business logic function.

• The business logic function calls a database query.

• Database query is called by a notification service.

One hop expansion captures the full chain.

Step 4: Output DONE, PARTIAL, MISSING with citations

Once the code graph is explored, Phase 1 outputs the result with specific file citations.

DONE example: AC: "Users can delete account" – DONE (src/users/api.ts:42, src/users/service.ts:156, src/db/queries.ts:203)

PARTIAL example: AC: "Data purged within 30 days" – PARTIAL. Found: database deletion scheduled (src/jobs/cleanup.ts:78). Missing: 30-day retention check.

MISSING example: AC: "Confirmation email sent" – MISSING. No email service found in codebase.

The step-by-step playbook

Step 1: Connect your requirements source

Phase 1 needs to read your acceptance criteria. Connect:

• Jira: pull acceptance criteria from story descriptions and custom fields

• Confluence: upload or sync specification pages

• Word/Markdown: upload requirement documents

• Custom database: point Phase 1 to your requirements API

Step 2: Point to your codebase

Phase 1 needs access to your code:

• GitHub/GitLab: grant read access to repository

• Private repositories: configure SSH key or token

• Multiple repos: configure all that are part of this release

• Branches: specify which branches to analyze (main, release branch, etc.)

Step 3: Run Phase 1 gap analysis

Trigger the analysis. Phase 1 will:

• Extract all acceptance criteria from requirements

• Perform hybrid retrieval on codebase

• Expand one hop along code graph for each match

• Generate report with DONE / PARTIAL / MISSING status

This typically takes 5 to 30 minutes depending on codebase size.

Step 4: Review and interpret results

Read the report. For each acceptance criterion, you see:

• Status (DONE / PARTIAL / MISSING)

• Files that implement it (with line numbers)

• Confidence score (how confident Phase 1 is in the match)

• Notes about what was found and what might be missing

Step 5: Act on the findings

For each PARTIAL or MISSING criterion:

• If MISSING: decide if it is a critical gap. If yes, add it to the backlog or delay the release.

• If PARTIAL: determine what is actually missing. Ask the developer. Update the requirement or the code.

• Verify DONE results: spot-check a few files to make sure Phase 1 understood correctly.

Interpreting confidence scores

Phase 1 assigns a confidence score (0 to 100) to each match. High confidence means the code clearly implements the criterion. Low confidence means the match is uncertain.

• 90-100: very confident; accept the result

• 70-89: moderately confident; review the cited files

• 50-69: uncertain; ask a developer to confirm

• Below 50: likely incorrect; investigate

Use confidence scores to prioritize your review effort.

Common scenarios and how to handle them

Scenario: PARTIAL result and you disagree

Phase 1 says requirement is partial, but you think it is done. Look at what Phase 1 found. Usually, it found part of the implementation and missed the rest due to naming or structure differences. Verify by reading the code. Then decide: is Phase 1 right (incomplete) or wrong (complete but hidden)?

Scenario: MISSING but you know the code exists

The code exists but Phase 1 missed it. This means hybrid retrieval did not find it. Reasons:

• Code is in a different service or module that was not scanned

• Code uses completely different terminology

• The criterion description is vague and did not match any code pattern

Either expand the search (add more repos) or clarify the criterion.

Scenario: Many MISSING results in one area

If entire sections show MISSING (e.g., all payment processing criteria), it usually means:

• The code does not exist at all (real gap)

• The code is in a different repo that was not scanned

• The requirements are too vague for Phase 1 to match

Investigate and decide next steps.

Using Phase 1 in your workflow

Run Phase 1:

• After code review and before merge to main (catch gaps early)

• Before every release (gate your shipping)

• As part of sprint retro (understand what was really shipped)

• When auditors ask (prove coverage with citations)

Next steps

Phase 1 tells you what acceptance criteria are not implemented. Phase 2 tells you what code has no requirement. Together, they give you the complete gap picture.

Try Phase 1 on your next feature. Run it before release. See which criteria you thought were done but actually are not.

Try Phase 1 on your project. Find unimplemented requirements. Try it now.