rdb-discovery/context/gap-analysis-model.md

Discovery Gap Analysis Model

This document defines how missing or weak project context should be detected and converted into targeted follow-up discovery questions.

It is a planning artifact for TASK-026 implementation. No code has been implemented.

---

Overview

When rdb generate populates context files from discovery answers, some sections will remain empty or contain only placeholders because:

• No discovery question addressed them
• The answer had Low confidence (filtered out)
• The mapping did not route data to that section
• The section does not exist in the template

Gap analysis detects these cases and generates targeted follow-up questions instead of leaving them as TBD.

---

1. Gap Detection Rules

A gap exists when one or more of the following conditions hold:

Rule ID	Condition	Example
GAP-01	A context file section contains only a TBD or TDB placeholder	## Mission\n\nTBD — What is the organisation's core mission?
GAP-02	A context file section exists in the template but no discovery answer mapped to it	## Monitoring & Alerting has no mapped source from any Q-id
GAP-03	A section contains partial content with unresolved sub-items (e.g., blank list entries, empty brackets)	Section has text but a required sub-list item is missing
GAP-04	An entire context file exists but has fewer than 50 characters of non-whitespace content beyond the heading	File is effectively empty

Detection operates per section within each context file, not at the file level. A file with partial data may have gaps in some sections and none in others.

---

2. Gap Severity Levels

Severity	Label	Criteria	Action Required
S1	Critical	The gap is in a section required for the current BUILDING stage. Blocking on this gap would stop all downstream work.	Must be resolved before moving to REVIEW_READY
S2	Important	The gap is in a section that will affect future implementation decisions but does not block immediate work.	Resolve within 1 BUILDING cycle (next discovery round)
S3	Low	The gap adds useful detail but is not needed for any active or planned task.	Can be deferred to REVIEW_READY or later

Severity assignment logic:

• A gap is S1 if its section appears in the current stage's expected files and any open TASK references that section
• A gap is S2 if its section is referenced by a mapped discovery question (Q-001 to Q-014) but no High/Medium confidence answer was produced
• A gap is S3 if the section exists in templates.py, has no mapped discovery question, and does not appear in any active task

---

3. Question Generation Rules

Follow-up questions are generated according to these rules:

Rule	Guidance	Example
QG-01	One gap maps to exactly one follow-up question — do not bundle multiple gaps into a single question	Separate ## Mission and ## Customers / Users even if both are in company-context.md
QG-02	Questions must be answerable with the original discovery format (text answer + confidence)	Ask for specific facts, not open-ended essays
QG-03	The question text should reference the target section so the responder understands context	"What is the team's core mission statement?" rather than "Tell us about your company"
QG-04	If a gap maps to a table format section, specify the table columns needed	For risks.md: "What security risk affects data retention? Provide impact and mitigation."
QG-05	Do not generate questions for sections already filled with non-TBD content	Skip ## Mission if it reads "We build developer tools"
QG-06	Prefer questions that can be answered by the project owner or a technical lead, not external experts	"Which cloud provider hosts production?" rather than "Describe your AWS architecture" unless already established

---

4. Question Prioritisation Rules

Follow-up questions are prioritised using this ordered scheme:

1. Severity first — All S1 gaps before all S2 gaps; all S2 before all S3
2. File completeness within severity — Files with more gaps are addressed earlier (reduce file-level churn)
3. Dependency order — If answering gap A enables answers to gap B, place A first
4. Question scope — Within equal priority, shorter/closer-to-answer questions come first

For example: ## Mission (S1, company-context.md) and ## Hosting (S1, infrastructure-context.md) are both S1; company-context.md goes first because it has 3 unresolved gaps versus infrastructure-context.md's 2.

---

5. Gap-to-Question Mapping

This mapping covers every template section that can contain TBD placeholders. For each section it defines: the gap trigger, the follow-up question to ask, and the target discovery question ID for the follow-up entry.

context/company-context.md

Section	Trigger	Follow-up Question	Discovery Q-ID
## Mission	Contains only TBD/placeholder text	"What is the organisation's core mission or purpose?"	New (Q-015-style)
## Products & Services	Contains only TBD/placeholder text	"List the products or services the organisation offers. What does each one do?"	New
## Customers / Users	Contains only TBD/placeholder text	"Who are the primary customers or users of your products? Use bullet points for each distinct user type."	New
## Brand & Positioning	Contains only TBD/placeholder text	"How does the organisation position itself in the market?"	New
## Key Stakeholders	Contains only TBD/placeholder text	"Who are the key stakeholders (names, roles, contact) for this project?"	New

context/product-brief.md

Section	Trigger	Follow-up Question	Discovery Q-ID
## Problem	Contains only TBD/placeholder text	"What problem is this product solving? Describe the customer pain and desired outcome."	Mirrors Q-001
## Users	Contains only TBD/placeholder text	"Who are the users of this product? List personas, roles, or segments."	Mirrors Q-002
## Success Criteria	Contains only TBD/placeholder text	"How will you measure success for this product? Be specific and verifiable."	Mirrors Q-003
## Minimum Useful Version	Contains only TBD/placeholder text	"What is the minimum set of features that delivers real value to users?"	Mirrors Q-004

context/project-brief.md

Section	Trigger	Follow-up Question	Discovery Q-ID
## Problem Statement	Contains only TBD/placeholder text	"Restate the product problem in project-specific terms. Include scope boundaries."	Mirrors Q-001
## Target Audience	Contains only TBD/placeholder text	"Who is the intended audience for this project? Who benefits from the final product?"	Mirrors Q-011
## Key Features (MVP)	Contains only TBD/placeholder text	"List the minimum set of features for the first release. Each feature should be independently valuable."	Mirrors Q-004
## Success Metrics	Contains only TBD/placeholder text	"How will you measure success for this project? Include specific thresholds or targets."	Mirrors Q-003
## Timeline & Milestones	Contains only TBD/placeholder text	"What are the expected delivery dates and key milestones?"	New (Q-015-style)

context/architecture.md

Section	Trigger	Follow-up Question	Discovery Q-ID
## Overview	Contains only TBD/placeholder text	"Describe the high-level system architecture. What design principles or patterns apply?"	Mirrors Q-012
## Core Components	Contains only TBD/placeholder text	"List the main modules, services, or packages and their responsibilities."	Mirrors Q-012
## Data Flow	Contains only TBD/placeholder text	"How does data move through the system? Describe entities, storage, and movement between components."	Mirrors Q-005
## External Integrations	Contains only TBD/placeholder text	"What external systems, APIs, or services must this connect to?"	Mirrors Q-006
## Deployment Architecture	Contains only TBD/placeholder text	"Describe the deployment layout, scaling strategy, and process."	Mirrors Q-010

context/decisions.md

Section	Trigger	Follow-up Question	Discovery Q-ID
Table body (no rows)	Has 0 data rows in the decision table	"What architecture or design decisions have been made? Record each with reason and date."	New

context/risks.md

Section	Trigger	Follow-up Question	Discovery Q-ID
Table body (no rows)	Has 0 data rows in the risks table	"What are the project risks? For each, describe impact and mitigation strategy."	Mirrors Q-007

context/assumptions.md

Section	Trigger	Follow-up Question	Discovery Q-ID
Table body (no rows)	Has 0 data rows in the assumptions table	"What are you assuming about this project? For each, note confidence and whether validation is needed."	Mirrors Q-008

context/development-context.md

Section	Trigger	Follow-up Question	Discovery Q-ID
## Tech Stack	Contains only TBD/placeholder text	"What is the technology stack? List languages, frameworks, libraries, and tooling."	Mirrors Q-012
## Coding Standards	Contains only TBD/placeholder text	"Are there agreed coding standards? Describe style conventions, naming patterns, linters, and formatters."	New
## Repository Structure	Contains only TBD/placeholder text	"Describe the repository directory layout and module organisation."	Mirrors Q-012
## Build & Test	Contains only TBD/placeholder text	"How do you build, test, and run this codebase locally? Include commands and setup steps."	Mirrors Q-009
## Dependencies	Contains only TBD/placeholder text	"What external services, databases, or third-party APIs are required?"	Mirrors Q-006

context/infrastructure-context.md

Section	Trigger	Follow-up Question	Discovery Q-ID
## Hosting	Contains only TBD/placeholder text	"Where is the application hosted? Specify cloud provider, on-prem details, or container orchestration."	Mirrors Q-013
## Environments	Contains only TBD/placeholder text	"What environments exist (dev/staging/prod)? Describe each and data management approach."	Mirrors Q-013
## CI / CD Pipeline	Contains only TBD/placeholder text	"Describe the build, test, and deployment pipeline configuration."	Mirrors Q-013
## Monitoring & Alerting	Contains only TBD/placeholder text	"What tools are used for monitoring, logging, and alerting?"	Mirrors Q-013
## Security	Contains only TBD/placeholder text	"What authentication models, data protection requirements, compliance needs, and access control policies apply?"	Mirrors Q-013

context/agent-guidelines.md

Section	Trigger	Follow-up Question	Discovery Q-ID
## Purpose	Contains only TBD/placeholder text	"What should agents or developers know about working on this project? Note constraints and conventions."	Mirrors Q-014
## Preferred Tools	Contains only TBD/placeholder text	"Which editors, debuggers, testing frameworks, and CLI tools are recommended?"	Mirrors Q-014
## Testing Preferences	Contains only TBD/placeholder text	"How should tests be written, run, and verified for this project?"	Mirrors Q-009
## Common Tasks	Contains only TBD/placeholder text	"What are the typical workflows for developers or AI agents on this project?"	New
## Known Gotchas	Contains only TBD/placeholder text	"Are there known pitfalls, quirks, or important caveats to be aware of?"	New

context/repository-context.md

Section	Trigger	Follow-up Question	Discovery Q-ID
## Purpose	Contains only TBD/placeholder text	"What is this repository's overall purpose and scope? What is it responsible for (and not responsible for)?"	Mirrors Q-014
## Key Components	Contains only TBD/placeholder text	"List the key components or modules in this repository."	Mirrors Q-012
## Dependencies	Contains only TBD/placeholder text	"What project dependencies exist? List external services, databases, and third-party APIs."	Mirrors Q-006
## Contributing	Contains only TBD/placeholder text	"Describe the contribution process: branch strategy, code review requirements, testing expectations."	Mirrors Q-014

context/open-questions.md

Section	Trigger	Follow-up Question	Discovery Q-ID
Table body (no rows)	Has 0 data rows	"Are there any open questions that need further investigation before implementation begins?"	New

project-level files (PROJECT_STATE.md, AGENT_HANDOFF.md, TASKS.md, TEST_PLAN.md, RUN_LOG.md)

These files are managed by CLI commands, not by discovery answers. They are not subject to gap analysis. Gaps in these files are handled by command logic, not by question generation.

---

6. Example Gap-to-Question Flow

Here is an end-to-end example of how the model operates:

Step 1 — Gap Detection

rdb context-status or a dedicated gap analysis scan finds:

File	Section	Gap Rule	Severity
context/company-context.md	## Mission	GAP-01 (TBD placeholder)	S1
context/company-context.md	## Key Stakeholders	GAP-01 (TBD placeholder)	S2
context/infrastructure-context.md	## Hosting	GAP-01 (TBD placeholder)	S1
context/infrastructure-context.md	## Monitoring & Alerting	GAP-01 (TBD placeholder)	S2
context/development-context.md	## Coding Standards	GAP-01 (TBD placeholder)	S3

Step 2 — Prioritisation

Sorted by severity, then file completeness:

1. S1 — company-context.md / ## Mission (company has 5 gaps vs infra's 4)
2. S1 — infrastructure-context.md / ## Hosting
3. S2 — company-context.md / ## Key Stakeholders
4. S2 — infrastructure-context.md / ## Monitoring & Alerting
5. S3 — development-context.md / ## Coding Standards

Step 3 — Question Generation

Follow-up questions appended to context/discovery-log.md:

New ID	Follow-up Question	Source Gap	Confidence Expected
Q-015	"What is the organisation's core mission or purpose?"	company-context.md ## Mission	High
Q-016	"Where is the application hosted? Specify cloud provider, on-prem details, or container orchestration."	infrastructure-context.md ## Hosting	High
Q-017	"Who are the key stakeholders (names, roles, contact) for this project?"	company-context.md ## Key Stakeholders	Medium
Q-018	"What tools are used for monitoring, logging, and alerting?"	infrastructure-context.md ## Monitoring & Alerting	Medium
Q-019	"Are there agreed coding standards? Describe style conventions, naming patterns, linters, and formatters."	development-context.md ## Coding Standards	Low

Step 4 — Regeneration

After answers to Q-015 through Q-019 are collected:

• Run rdb generate (or re-run gap analysis)
• Sections populated from new answers should resolve the S1 and S2 gaps
• Remaining gaps re-prioritise for the next cycle

---

7. Edge Cases

Case	Handling
Section contains partial text + TBD sub-items	Only generate a question for the missing sub-item, not the entire section
Section text reads "TBD" but it is actually correct (intentional placeholder)	Provide a skip/confirm mechanism — let the user mark as "acceptable" to suppress the gap
Template adds new sections in future versions	Sections with no mapping entry default to S3 severity with a generic question: "What information belongs in this section?"
A section maps to multiple discovery questions	Generate separate follow-ups per unmapped question, each linked to its source Q-id
File has fewer than 50 characters (GAP-04) but the heading is meaningful	Count content beyond the heading line only

---

8. Implementation Task: TASK-026

Scope for TASK-026 (Implementation)

TASK-026 will implement a CLI command rdb gap that:

1. Reads all 18 template-based context files listed in templates.py CONTEXT_FILES
2. For each file, scans every section for GAP-01 (TBD), GAP-03 (partial content), or GAP-04 (near-empty file)
3. For each gap found, applies severity rules from Section 2
4. Generates follow-up questions using the mapping in Section 5
5. Prioritises questions per Section 4
6. Outputs the prioritised question list to stdout
7. Optionally appends answers to context/discovery-log.md when a user provides them interactively

What TASK-026 Does NOT Do

• Does not auto-populate context files — that remains rdb generate's scope
• Does not replace rdb discover — follow-up questions are new entries in discovery-log.md
• Does not change the existing gap analysis model document

Expected Module Structure (TASK-026)

src/rdb_discovery/gap_analysis.py       # Core detection and question generation logic
tests/test_gap_analysis.py              # Unit tests for each section mapping

Expected Test Requirements (TASK-026)

Test Category	Count	Description
Gap detection per template section	~25	One per section in the mapping table
Severity classification	3+	S1, S2, S3 on representative inputs
Question generation format	5+	Follow-up questions match QG-01 through QG-06 rules
Prioritisation ordering	3+	Sorted output matches severity → completeness → dependency → scope
Edge cases (Section 6)	5+	Partial sections, acceptable TBDs, new template sections, multi-question sections
CLI command rdb gap	4+	Help text, empty project handling, discovery-log append mode

---

9. How This Model Relates to the Rest of RDB

discovery-log.md          (source of truth for all answers)
        │
        ▼
   rdb discover / rdb gap     (collects or generates questions)
        │
        ▼
   rdb generate               (maps answers → context files via discovery-context-mapping.md)
        │
        ▼
   rdb context-status         (reports health, can trigger gap analysis)
        │
        ▼
   rdb gap                    (detects remaining gaps → new questions)
        │
        └───────────────────►  loop back to rdb discover for follow-up answers

This model connects to:

• context/discovery-context-mapping.md — the existing Q-001 to Q-014 mapping (this model extends it with follow-up question generation)
• src/rdb_discovery/templates.py — the authoritative list of template sections used for detection
• rdb context-status — health reporting can surface gap counts as an additional metric

---

This document is a planning artifact. No code has been implemented. TASK-026 will implement the CLI command based on this model.