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.*