From 250cf9316a101fa4bb1d053c51929f2792e730d2 Mon Sep 17 00:00:00 2001 From: robbond Date: Tue, 2 Jun 2026 18:36:42 +0100 Subject: [PATCH] feat(task-019): define discovery-to-context mappings --- .rdb/session-log.jsonl | 5 + PROJECT_STATE.md | 2 +- TASKS.md | 25 +++- context/discovery-context-mapping.md | 184 +++++++++++++++++++++++++++ tests/test_discovery_mapping.py | 103 +++++++++++++++ 5 files changed, 317 insertions(+), 2 deletions(-) create mode 100644 context/discovery-context-mapping.md create mode 100644 tests/test_discovery_mapping.py diff --git a/.rdb/session-log.jsonl b/.rdb/session-log.jsonl index 2858fa3..1fd7f4c 100644 --- a/.rdb/session-log.jsonl +++ b/.rdb/session-log.jsonl @@ -41,3 +41,8 @@ {"timestamp": "2026-06-02T16:57:29.853052+00:00", "event_type": "command", "target": "rdb prompt", "details": {}} {"timestamp": "2026-06-02T17:05:41.754949+00:00", "event_type": "command", "target": "rdb status", "details": {}} {"timestamp": "2026-06-02T17:07:48.597850+00:00", "event_type": "command", "target": "rdb status", "details": {}} +{"timestamp": "2026-06-02T17:10:43.959746+00:00", "event_type": "command", "target": "rdb status", "details": {}} +{"timestamp": "2026-06-02T17:10:48.601943+00:00", "event_type": "command", "target": "rdb next", "details": {}} +{"timestamp": "2026-06-02T17:10:57.679687+00:00", "event_type": "command", "target": "rdb prompt", "details": {}} +{"timestamp": "2026-06-02T17:22:38.052771+00:00", "event_type": "command", "target": "rdb status", "details": {}} +{"timestamp": "2026-06-02T17:35:19.867986+00:00", "event_type": "command", "target": "rdb status", "details": {}} diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index 0b9f065..668c571 100644 --- a/PROJECT_STATE.md +++ b/PROJECT_STATE.md @@ -4,7 +4,7 @@ Current Stage: BUILDING Previous Stage: BOOTSTRAP_READY Next Stage: REVIEW_READY -Current Task: TASK-015 +Current Task: TASK-019 Active Branch: main Last Updated: 2026-06-02 diff --git a/TASKS.md b/TASKS.md index f2390ff..c09cd10 100644 --- a/TASKS.md +++ b/TASKS.md @@ -337,7 +337,7 @@ Definition of Done: ## TASK-019 — Define discovery-to-context mappings -Status: Todo +Status: Done Role: Architecture Agent @@ -364,6 +364,29 @@ Definition of Done: - Mapping covers all discovery questions - Future implementation work is clearly defined +Result + +Created `context/discovery-context-mapping.md` which documents: + +- Reference table of all 10 core discovery questions (Q-001 through Q-010) +- Reference table of all target context files and their purpose +- Detailed mapping for each question to primary and secondary context files with specific section guidance +- Summary question-to-file matrix for quick reference +- Implementation notes defining how future code should read discovery answers and populate context files +- Constraints for future implementation (preserve existing content, skip low-confidence answers) +- Test requirements for when code is eventually written + +Added `tests/test_discovery_mapping.py` with 6 tests validating: + +- Mapping file existence +- All 10 core questions are present +- Table-format documentation section exists +- Summary matrix section exists +- Future implementation notes exist (and clarify no code has been implemented yet) +- All context files from templates.py are referenced in the mapping + +No context generation implementation was added — this task is a planning artifact only. + ## TASK-020 — Generate context files from discovery answers Status: Todo diff --git a/context/discovery-context-mapping.md b/context/discovery-context-mapping.md new file mode 100644 index 0000000..011b176 --- /dev/null +++ b/context/discovery-context-mapping.md @@ -0,0 +1,184 @@ +# Discovery-to-Context Mapping + +This document defines how answers to the 10 core discovery questions should be transformed into project context files. + +## Reference: Core Discovery Questions + +| ID | Question | +|---|---| +| Q-001 | What problem are we solving? | +| Q-002 | Who is the user? | +| Q-003 | What does success look like? | +| Q-004 | What is the minimum useful version? | +| Q-005 | What data do we need? | +| Q-006 | What systems must it connect to? | +| Q-007 | What are the risks? | +| Q-008 | What must not happen? | +| Q-009 | How will we test it? | +| Q-010 | How will it be deployed? | + +## Reference: Target Context Files + +All paths are relative to the project root. + +| File | Purpose | +|---|---| +| `context/discovery-log.md` | Source of discovery answers — not a target, but the input to mapping | +| `context/product-brief.md` | Product vision, users, success criteria, MVP scope | +| `context/project-brief.md` | Detailed project brief with problem statement and timeline | +| `context/architecture.md` | System design, components, data flow, integrations, deployment | +| `context/decisions.md` | Architecture and design decision records (ADR-style table) | +| `context/risks.md` | Risk register with impact and mitigation columns | +| `context/assumptions.md` | Project assumptions with confidence and validation status | +| `context/open-questions.md` | Open questions needing further investigation | +| `context/development-context.md` | Tech stack, coding standards, build/test instructions | +| `context/infrastructure-context.md` | Hosting, environments, CI/CD, monitoring, security | +| `context/agent-guidelines.md` | Agent operating rules for this project | +| `context/company-context.md` | Company goals and constraints that shape the project | +| `context/repository-context.md` | Repository structure, workflow, and contributing info | +| `TEST_PLAN.md` | Manual and automated test plan | + +## Mapping: Question → Context Files + Sections + +### Q-001 — What problem are we solving? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/product-brief.md` | `## Problem` | The raw answer fills in the product problem statement. If the answer is vague, split it into customer pain and desired outcome. | +| `context/project-brief.md` | `## Problem Statement` | Restate in project-specific terms. Include scope boundaries if mentioned. | +| `context/company-context.md` | (append to Goals) | Link back to company-level goals if the answer references them. | + +### Q-002 — Who is the user? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/product-brief.md` | `## Users` | Record user personas, roles, or segments. Use bullet points for each distinct user type. | +| `context/company-context.md` | `## Customers / Users` | If the answer identifies external customers rather than internal users, append to this section. | +| `context/development-context.md` | `## IDEs and Editors` | Note any tooling constraints specific to the target users (if they are developers). | + +### Q-003 — What does success look like? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/product-brief.md` | `## Success Criteria` | Record measurable success criteria as a numbered or bulleted list. Each criterion should be verifiable. | +| `context/project-brief.md` | `## Success Metrics` | Restate with specific measurement approach (e.g., user count, latency threshold, coverage %). | + +### Q-004 — What is the minimum useful version? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/product-brief.md` | `## Minimum Useful Version` | List MVP features as bullet points. Each feature should be independently valuable. | +| `context/project-brief.md` | `## Key Features (MVP)` | Expand with brief descriptions for each MVP feature. | +| `TASKS.md` | New TASK entries | Consider generating initial task rows from MVP features. | + +### Q-005 — What data do we need? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/architecture.md` | `## Data Flow` | Describe data entities, storage locations, and movement between components. | +| `context/development-context.md` | `## Dependencies` | Record database platforms, storage services, or data stores required. | +| `context/infrastructure-context.md` | `## Environments` | Note any data requirements per environment (dev/staging/prod data parity). | + +### Q-006 — What systems must it connect to? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/architecture.md` | `## External Integrations` | List each external system with its role (API, database, auth provider, etc.). | +| `context/infrastructure-context.md` | Append as section | If the integration requires infrastructure changes, document there. | +| `context/decisions.md` | New row | If integration choices involved trade-offs, record as a decision. | + +### Q-007 — What are the risks? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/risks.md` | Data rows | Each risk becomes a row with columns: ID, Risk Description, Impact (High/Med/Low), Mitigation, Status. Assign sequential IDs like RISK-001. | +| `context/open-questions.md` | New rows | Any unresolved aspects of a risk become open questions. | + +### Q-008 — What must not happen? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/assumptions.md` | Data rows | Constraints that are actually assumptions about what won't be done. Record confidence and validation need. | +| `context/decisions.md` | New row | If a "must not" is the result of an active decision (e.g., "no third-party auth"), record as a decision with reasoning. | +| `context/open-questions.md` | New rows | Any constraint that needs clarification becomes an open question. | + +### Q-009 — How will we test it? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/development-context.md` | `## Build & Test` | Document test framework, test execution commands, and local setup steps. | +| `TEST_PLAN.md` | Manual/Automated sections | Convert into the test plan with specific test cases. Each discovery answer becomes one or more test entries. | + +### Q-010 — How will it be deployed? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/architecture.md` | `## Deployment Architecture` | Describe the deployment layout, scaling strategy, and process. | +| `context/infrastructure-context.md` | `## CI / CD Pipeline`, `## Hosting`, `## Environments` | Fill in hosting platform, environment details, and pipeline steps from the discovery answer. | + +## Summary: Question-to-File Matrix + +This matrix provides a quick-reference view of all mappings. "Primary" means the answer should go there first; "Secondary" means it may also be updated if relevant. + +| Q-ID | Question | Primary Context Files | Secondary Context Files | +|---|---|---|---| +| Q-001 | What problem are we solving? | product-brief.md, project-brief.md | company-context.md | +| Q-002 | Who is the user? | product-brief.md, company-context.md | development-context.md | +| Q-003 | What does success look like? | product-brief.md, project-brief.md | — | +| Q-004 | Minimum useful version? | product-brief.md, project-brief.md | TASKS.md | +| Q-005 | What data do we need? | architecture.md, development-context.md | infrastructure-context.md | +| Q-006 | Systems to connect to? | architecture.md, infrastructure-context.md | decisions.md | +| Q-007 | What are the risks? | risks.md, open-questions.md | — | +| Q-008 | What must not happen? | assumptions.md, decisions.md | open-questions.md | +| Q-009 | How will we test it? | development-context.md, TEST_PLAN.md | — | +| Q-010 | How will it be deployed? | architecture.md, infrastructure-context.md | — | + +## Implementation Notes for Future Work + +This document is a planning artifact. No code generation has been implemented yet. + +### What future implementation should do + +1. **Read** discovery-log.md (via `read_discovery_answers` in `discovery.py`) +2. **Classify** each answer by its question ID +3. **Transform** the answer text according to this mapping's section guidance +4. **Write** or update target context files, creating rows in tables where applicable +5. **Preserve** existing content — never overwrite sections without explicit user intent +6. **Record** what was generated so the user can review + +### Constraints for future implementation + +- Only process answers with High or Medium confidence +- Skip Low confidence answers (these should be handled by `ask-more` first) +- Use template format from `templates.py` as the base for context files +- Add new sections only if a discovery answer introduces entirely new content areas +- Log each mapping action to `.rdb/session-log.jsonl` for traceability + +### Test requirements for future implementation + +When code is eventually written, tests should verify: + +- Each question ID maps to exactly the files listed in this document +- Empty/placeholder sections are populated correctly +- Existing file content is preserved (not overwritten) +- The matrix above passes programmatic validation against the mapping data diff --git a/tests/test_discovery_mapping.py b/tests/test_discovery_mapping.py new file mode 100644 index 0000000..30c1e4f --- /dev/null +++ b/tests/test_discovery_mapping.py @@ -0,0 +1,103 @@ +"""Tests for the discovery-to-context mapping document.""" + +from pathlib import Path + +# Path to the mapping document (relative to project root) +MAPPING_FILE = "context/discovery-context-mapping.md" + + +def _get_project_root() -> Path: + """Return the project root directory. + + Walk up from this file's location to find the repo root. + """ + # Start from tests/ and walk up + current = Path(__file__).resolve().parent.parent + # Look for pyproject.toml or .git as markers + while current != current.parent: + if (current / "pyproject.toml").exists() or (current / ".git").exists(): + return current + current = current.parent + return Path.cwd() + + +def test_mapping_file_exists() -> None: + """The discovery-to-context mapping file must exist.""" + root = _get_project_root() + mapping_path = root / MAPPING_FILE + assert mapping_path.exists(), f"Mapping file missing: {mapping_path}" + + +def test_mapping_contains_all_10_questions() -> None: + """Every core discovery question must appear in the mapping.""" + from rdb_discovery.templates import CORE_QUESTIONS + + root = _get_project_root() + mapping_path = root / MAPPING_FILE + content = mapping_path.read_text(encoding="utf-8") + + for question in CORE_QUESTIONS: + assert question in content, f"Question not mapped: {question}" + + +def test_mapping_documentation_contains_table_format() -> None: + """The mapping must be documented in a table format (machine-readable).""" + root = _get_project_root() + mapping_path = root / MAPPING_FILE + content = mapping_path.read_text(encoding="utf-8") + + # Accept both the exact header and any variant that contains the key phrase + has_section = ("Mapping: Question" in content or "Question → Context" in content) + assert has_section, ( + "Missing 'Mapping: Question -> Context Files + Sections' section header" + ) + + +def test_mapping_contains_summary_matrix() -> None: + """A summary question-to-file matrix table must exist.""" + root = _get_project_root() + mapping_path = root / MAPPING_FILE + content = mapping_path.read_text(encoding="utf-8") + + assert "Question-to-File Matrix" in content, ( + "Missing 'Question-to-File Matrix' summary section" + ) + + +def test_mapping_contains_future_implementation_notes() -> None: + """The mapping must define future implementation guidance.""" + root = _get_project_root() + mapping_path = root / MAPPING_FILE + content = mapping_path.read_text(encoding="utf-8") + + assert "## Implementation Notes" in content or "## What future implementation should do" in content, ( + "Missing 'Implementation Notes' section" + ) + # Verify it clearly states no code has been implemented yet + assert "No code generation has been implemented" in content, ( + "Must clarify that mapping is a planning artifact with no code yet" + ) + + +def test_mapping_covers_all_context_files() -> None: + """Every context file listed in templates.py must appear in the mapping.""" + from rdb_discovery.templates import CONTEXT_FILES + + # Filter out control files (TASKS.md, PROJECT_STATE.md, etc.) and keep context files + context_paths = {p for p in CONTEXT_FILES if p.startswith("context/")} + + root = _get_project_root() + mapping_path = root / MAPPING_FILE + content = mapping_path.read_text(encoding="utf-8") + + # Extract file paths from the mapping's Reference section + found_files = set() + for line in content.splitlines(): + for cp in context_paths: + if f"`{cp}`" in line or cp in line: + found_files.add(cp) + + for cp in context_paths: + assert any(cp in fp for fp in found_files), ( + f"Context file not referenced in mapping: {cp}" + )