From c72ad6995ebd88e10763f919803c0ef566ff970a Mon Sep 17 00:00:00 2001 From: robbond Date: Thu, 4 Jun 2026 07:42:48 +0100 Subject: [PATCH] feat(task-022): expand discovery coverage --- .rdb/session-log.jsonl | 31 ++++ TASKS.md | 229 ++++++++++++++++++++++++-- context/discovery-context-mapping.md | 52 +++++- src/rdb_discovery/generate_context.py | 26 +++ src/rdb_discovery/templates.py | 4 + tests/test_discovery.py | 4 +- tests/test_discovery_mapping.py | 6 +- tests/test_generate_context.py | 14 +- 8 files changed, 341 insertions(+), 25 deletions(-) diff --git a/.rdb/session-log.jsonl b/.rdb/session-log.jsonl index d784a1b..37fa086 100644 --- a/.rdb/session-log.jsonl +++ b/.rdb/session-log.jsonl @@ -81,3 +81,34 @@ {"timestamp": "2026-06-03T17:58:40.679715+00:00", "event_type": "command", "target": "rdb generate", "details": {}} {"timestamp": "2026-06-03T17:59:54.816018+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} {"timestamp": "2026-06-03T18:02:22.183984+00:00", "event_type": "command", "target": "rdb next", "details": {}} +{"timestamp": "2026-06-04T05:14:08.600178+00:00", "event_type": "command", "target": "rdb status", "details": {}} +{"timestamp": "2026-06-04T05:14:24.061826+00:00", "event_type": "command", "target": "rdb status", "details": {}} +{"timestamp": "2026-06-04T05:14:38.336849+00:00", "event_type": "command", "target": "rdb next", "details": {}} +{"timestamp": "2026-06-04T05:14:49.894695+00:00", "event_type": "command", "target": "rdb prompt", "details": {}} +{"timestamp": "2026-06-04T05:19:45.385984+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T05:19:45.410121+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T05:19:45.438892+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T05:19:45.530897+00:00", "event_type": "command", "target": "rdb generate", "details": {}} +{"timestamp": "2026-06-04T05:21:43.139977+00:00", "event_type": "command", "target": "rdb status", "details": {}} +{"timestamp": "2026-06-04T05:39:05.966198+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T05:39:05.991663+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T05:39:06.022398+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T05:39:06.155411+00:00", "event_type": "command", "target": "rdb generate", "details": {}} +{"timestamp": "2026-06-04T05:51:40.975066+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T05:51:41.000251+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T05:51:41.030414+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T05:51:41.111721+00:00", "event_type": "command", "target": "rdb generate", "details": {}} +{"timestamp": "2026-06-04T06:06:03.436361+00:00", "event_type": "command", "target": "rdb status", "details": {}} +{"timestamp": "2026-06-04T06:27:22.527128+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T06:27:22.551624+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T06:27:22.585367+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T06:27:22.683899+00:00", "event_type": "command", "target": "rdb generate", "details": {}} +{"timestamp": "2026-06-04T06:33:49.312031+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T06:33:49.331790+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T06:33:49.361065+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T06:33:49.443458+00:00", "event_type": "command", "target": "rdb generate", "details": {}} +{"timestamp": "2026-06-04T06:38:18.966356+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T06:38:18.991294+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T06:38:19.019668+00:00", "event_type": "command", "target": "rdb context-status", "details": {}} +{"timestamp": "2026-06-04T06:38:19.108828+00:00", "event_type": "command", "target": "rdb generate", "details": {}} +{"timestamp": "2026-06-04T06:38:19.717117+00:00", "event_type": "command", "target": "rdb status", "details": {}} diff --git a/TASKS.md b/TASKS.md index 6b50aaa..4a0f475 100644 --- a/TASKS.md +++ b/TASKS.md @@ -503,33 +503,83 @@ Added `tests/test_context_status.py` with 26 tests across 4 classes: All 140 tests pass. -## TASK-022 — Generate Claude Code permission profile +## TASK-022 — Expand discovery coverage -Status: Todo +Status: Done -Role: Documentation Agent +Role: Architecture Agent Goal: - -Create a recommended Claude Code permissions configuration for RDB workflows. +Collect enough information to populate all standard context files. Implementation Gap: - -Claude Code permission settings are not currently documented, resulting in unnecessary approval prompts and inconsistent behaviour between projects. +Several context files remain mostly placeholders because discovery questions do not collect the information required to populate them. Acceptance Criteria: -- Define recommended safe commands for auto-approval -- Define commands that should require approval -- Document the profile in CLAUDE.md -- Include rationale for each category +- Review all context templates ✓ +- Identify unmapped sections ✓ +- Add additional discovery questions where required ✓ +- Update discovery-to-context mapping ✓ +- Add/update tests ✓ Definition of Done: -- Permission profile documented -- CLAUDE.md updated +- Every major template section has a discovery source ✓ +- Discovery-to-context mapping updated ✓ +- Tests pass ✓ (140, all passing) -## TASK-022 — Add objectivity and efficiency guidelines +Result + +Added 4 new grouped discovery questions (Q-011 through Q-014) covering all major unmapped sections: + +| Question ID | Category | Target Sections | +| ----------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------- | +| Q-011 | Organisation/project ownership | company-context.md Mission, project-brief.md Target Audience | +| Q-012 | Technology stack and repository structure | development-context.md Tech Stack, Coding Standards; architecture.md Overview, Core Components | +| Q-013 | Infrastructure/deployment/security | infrastructure-context.md Hosting, Environments, Monitoring & Alerting, Security | +| Q-014 | Agent/developer workflow | agent-guidelines.md Purpose and Preferred Tools; repository-context.md Purpose and Contributing | + +Coverage expanded from 16 section targets (10 questions) to 28 section targets (14 questions). + +Files modified: + +- `src/rdb_discovery/templates.py` — Added 4 new questions to CORE_QUESTIONS +- `src/rdb_discovery/generate_context.py` — Added Q-011 through Q-014 mappings; updated all_questions list in \_write_table_row +- `context/discovery-context-mapping.md` — Added 4 new question entries, detailed mapping tables, and summary matrix rows +- `tests/test_generate_context.py` — Updated question count assertions to use dynamic CORE_QUESTIONS +- `tests/test_discovery_mapping.py` — Renamed test to match dynamic question count +- `tests/test_discovery.py` — Updated assertion from exact 10 to >= 10 + +## TASK-023 — Improve generated context quality + +Status: Todo + +Role: Implementation Agent + +Goal: +Improve the quality and usefulness of generated context files after `rdb generate`. + +Implementation Gap: +`rdb generate` now writes discovery answers into some context files, but several useful context files remain mostly placeholders and some answers are mapped to weak or incorrect sections. + +Acceptance Criteria: + +- Populate `company-context.md` when discovery answers include users, product purpose, or stakeholders +- Populate `agent-guidelines.md` when answers include tools, constraints, risks, or testing preferences +- Populate `repository-context.md` when answers include project purpose, dependencies, or contribution/testing approach +- Do not map testing answers into timeline/milestone sections +- Fix `TDB` placeholder typos to `TBD` +- Preserve existing non-placeholder content +- Add/update regression tests using the current sample discovery-log data + +Definition of Done: + +- Running `rdb generate` on the sample discovery log produces useful content in more than just product/project brief files +- Context files contain fewer irrelevant placeholders +- Tests pass + +## TASK-024 — Add objectivity and efficiency guidelines Status: Todo @@ -556,3 +606,154 @@ Definition of Done: - `context/agent-guidelines.md` includes objectivity and efficiency guidance - Guidance helps reduce token usage without preventing useful technical reasoning - Existing workflow remains unchanged + +## TASK-025 — Discovery gap analysis + +Status: Todo + +Role: Implementation Agent + +Goal: +Identify missing context and generate targeted follow-up questions. + +Implementation Gap: +Context health can identify missing information, but there is no automated way to generate follow-up discovery questions from those gaps. + +Acceptance Criteria: + +- Analyse generated context files +- Detect empty sections +- Generate follow-up questions +- Link questions to missing context sections +- Add/update tests + +Definition of Done: + +- Gap analysis command exists +- Missing context produces targeted questions +- Tests pass + +## TASK-026 — Context-driven follow-up questions + +Status: Todo + +Role: Implementation Agent + +Goal: +Generate follow-up discovery questions based on previous answers. + +Implementation Gap: +Discovery questions are currently static and do not adapt based on project-specific answers. + +Acceptance Criteria: + +- Follow-up questions are generated from discovery answers +- Different answers produce different follow-up questions +- Rules are deterministic and testable +- Add/update tests + +Definition of Done: + +- Discovery flow becomes adaptive +- Follow-up questions are linked to discovery answers +- Tests pass + +## TASK-027 — Improve discovery answer reliability UX + +Status: Todo + +Role: Architecture Agent + +Goal: +Make answer reliability easier for users to understand during discovery. + +Implementation Gap: +Users are asked to provide a confidence level, but confidence is an internal implementation concept and may not reflect how users think about the reliability of information. + +Acceptance Criteria: + +- Review confidence collection workflow +- Define a more intuitive reliability model +- Maintain compatibility with existing confidence filtering +- Update discovery-to-context documentation +- Add/update tests if required + +Definition of Done: + +- Reliability terminology is documented +- Mapping to internal confidence levels is defined +- Future implementation work is clearly specified + +## TASK-028 — Capture AI tool targets + +Status: Todo + +Role: Architecture Agent + +Goal: +Allow discovery to capture which AI development tools will consume generated project context. + +Implementation Gap: +Generated context is currently tool-agnostic, but different tools require different guidance files and configuration formats. + +Acceptance Criteria: + +- Define supported tool categories: + - Claude Code + - Cline + - Cursor + - ChatGPT + - GitHub Copilot + - Local LLMs + - Other +- Add discovery question for AI tool usage +- Update discovery-to-context mapping +- Define which generated files are generic +- Define which generated files are tool-specific +- Do not implement tool-specific generation yet + +Definition of Done: + +- Tool model documented +- Discovery captures tool preferences +- Future generation requirements are defined + +## TASK-040 — Generate Claude Code permission profile + +Status: Todo + +Role: Documentation Agent + +Goal: + +Create a recommended Claude Code permissions configuration for RDB workflows. + +Implementation Gap: + +Claude Code permission settings are not currently documented, resulting in unnecessary approval prompts and inconsistent behaviour between projects. + +Acceptance Criteria: + +- Define recommended safe commands for auto-approval +- Define commands that should require approval +- Document the profile in CLAUDE.md +- Include rationale for each category + +Definition of Done: + +- Permission profile documented +- CLAUDE.md updated + +## TASK-050 — AI-assisted discovery questioning + +Status: Todo + +Goal: +Use an LLM to propose the most valuable next discovery questions. + +Acceptance Criteria: + +- Review existing context +- Review discovery history +- Suggest follow-up questions +- Keep human approval in the loop diff --git a/context/discovery-context-mapping.md b/context/discovery-context-mapping.md index 011b176..9d5c415 100644 --- a/context/discovery-context-mapping.md +++ b/context/discovery-context-mapping.md @@ -1,6 +1,6 @@ # Discovery-to-Context Mapping -This document defines how answers to the 10 core discovery questions should be transformed into project context files. +This document defines how answers to the 14 core discovery questions should be transformed into project context files. ## Reference: Core Discovery Questions @@ -16,6 +16,10 @@ This document defines how answers to the 10 core discovery questions should be t | Q-008 | What must not happen? | | Q-009 | How will we test it? | | Q-010 | How will it be deployed? | +| Q-011 | Who owns and directs the project, and what are its organisational goals? | +| Q-012 | What is the technology stack, repository structure, and architecture approach? | +| Q-013 | Where is it hosted, which environments exist, and what are the security requirements? | +| Q-014 | What agent and developer workflow tools, constraints, and guidelines apply? | ## Reference: Target Context Files @@ -136,6 +140,48 @@ Maps to: | `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. | +### Q-011 — Who owns and directs the project, and what are its organisational goals? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/company-context.md` | `## Mission` | Record the organisation's core mission, vision, or strategic goals that relate to this project. If no company-level mission exists, record the team's purpose. | +| `context/project-brief.md` | `## Target Audience` | Restate in project-specific terms — who will use or benefit from the final product? | + +### Q-012 — What is the technology stack, repository structure, and architecture approach? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/development-context.md` | `## Tech Stack` | Extract languages, frameworks, libraries, tooling, and build/test tools. Record each as a distinct item. | +| `context/development-context.md` | `## Coding Standards` | Note any style conventions, naming patterns, linters, formatters, or agreed-upon patterns. If none exist, note "TBD". | +| `context/architecture.md` | `## Overview` | Record high-level design principles, architectural patterns (e.g., monolith, microservices), and key design decisions. | +| `context/architecture.md` | `## Core Components` | List the main modules, services, or packages and their responsibilities. Use bullet points for each component. | + +### Q-013 — Where is it hosted, which environments exist, and what are the security requirements? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/infrastructure-context.md` | `## Hosting` | Record hosting platform (cloud provider, on-prem, container orchestration, etc.). | +| `context/infrastructure-context.md` | `## Environments` | List all environments (dev/staging/prod), their purpose, and data management approach. | +| `context/infrastructure-context.md` | `## Monitoring & Alerting` | Document monitoring tools, alerting channels, and observability requirements. | +| `context/infrastructure-context.md` | `## Security` | Record authentication models, data protection requirements, compliance needs, and access control policies. | + +### Q-014 — What agent and developer workflow tools, constraints, and guidelines apply? + +Maps to: + +| Context File | Section | Guidance | +|---|---|---| +| `context/agent-guidelines.md` | `## Purpose` | Record why agents need specific context for this project (constraints, conventions, expectations). | +| `context/agent-guidelines.md` | `## Preferred Tools` | List recommended editors, debuggers, testing frameworks, CLI tools, and automation tools. | +| `context/repository-context.md` | `## Purpose` | Record the project's overall purpose, scope boundaries, and what it is / is not responsible for. | +| `context/repository-context.md` | `## Contributing` | Document contribution process, branch strategy, code review requirements, and testing expectations for contributors. | + ## 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. @@ -152,6 +198,10 @@ This matrix provides a quick-reference view of all mappings. "Primary" means the | 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 | — | +| Q-011 | Who owns and directs the project? What are its organisational goals? | company-context.md, project-brief.md | — | +| Q-012 | What is the technology stack, repository structure, architecture approach? | development-context.md, architecture.md | — | +| Q-013 | Where is it hosted, which environments exist, and what are the security requirements? | infrastructure-context.md | — | +| Q-014 | What agent and developer workflow tools, constraints, and guidelines apply? | agent-guidelines.md, repository-context.md | — | ## Implementation Notes for Future Work diff --git a/src/rdb_discovery/generate_context.py b/src/rdb_discovery/generate_context.py index c69b6c6..f055b42 100644 --- a/src/rdb_discovery/generate_context.py +++ b/src/rdb_discovery/generate_context.py @@ -59,6 +59,28 @@ CONTEXT_MAP = { ("context/architecture.md", "## Deployment Architecture", "body"), ("context/infrastructure-context.md", None, "append"), ], + "Q-011": [ # Who owns and directs the project, and what are its organisational goals? + ("context/company-context.md", "## Mission", "body"), + ("context/project-brief.md", "## Target Audience", "body"), + ], + "Q-012": [ # What is the technology stack, repository structure, and architecture approach? + ("context/development-context.md", "## Tech Stack", "body"), + ("context/development-context.md", "## Coding Standards", "body"), + ("context/architecture.md", "## Overview", "body"), + ("context/architecture.md", "## Core Components", "body"), + ], + "Q-013": [ # Where is it hosted, which environments exist, and what are the security requirements? + ("context/infrastructure-context.md", "## Hosting", "body"), + ("context/infrastructure-context.md", "## Environments", "body"), + ("context/infrastructure-context.md", "## Monitoring & Alerting", "body"), + ("context/infrastructure-context.md", "## Security", "body"), + ], + "Q-014": [ # What agent and developer workflow tools, constraints, and guidelines apply? + ("context/agent-guidelines.md", "## Purpose", "body"), + ("context/agent-guidelines.md", "## Preferred Tools", "body"), + ("context/repository-context.md", "## Purpose", "body"), + ("context/repository-context.md", "## Contributing", "body"), + ], } @@ -201,6 +223,10 @@ def _write_table_row(target, section_header, answer): "What must not happen?", "How will we test it?", "How will it be deployed?", + "Who owns and directs the project, and what are its organisational goals?", + "What is the technology stack, repository structure, and architecture approach?", + "Where is it hosted, which environments exist, and what are the security requirements?", + "What agent and developer workflow tools, constraints, and guidelines apply?", ] question_text = all_questions[int(q_num) - 1] if int(q_num) <= len(all_questions) else answer["question"] diff --git a/src/rdb_discovery/templates.py b/src/rdb_discovery/templates.py index 818c6f4..7eb4983 100644 --- a/src/rdb_discovery/templates.py +++ b/src/rdb_discovery/templates.py @@ -13,6 +13,10 @@ CORE_QUESTIONS = [ "What must not happen?", "How will we test it?", "How will it be deployed?", + "Who owns and directs the project, and what are its organisational goals?", + "What is the technology stack, repository structure, and architecture approach?", + "Where is it hosted, which environments exist, and what are the security requirements?", + "What agent and developer workflow tools, constraints, and guidelines apply?", ] CONTEXT_FILES: dict[str, str] = { diff --git a/tests/test_discovery.py b/tests/test_discovery.py index c836845..28135e9 100644 --- a/tests/test_discovery.py +++ b/tests/test_discovery.py @@ -3,9 +3,9 @@ from pathlib import Path import rdb_discovery.discovery as discovery_mod -def test_core_questions_returns_10_items() -> None: +def test_core_questions_returns_at_least_10_items() -> None: questions = discovery_mod.core_questions() - assert len(questions) == 10 + assert len(questions) >= 10 def test_append_creates_file_when_missing(tmp_path: Path) -> None: diff --git a/tests/test_discovery_mapping.py b/tests/test_discovery_mapping.py index 30c1e4f..9e9306e 100644 --- a/tests/test_discovery_mapping.py +++ b/tests/test_discovery_mapping.py @@ -28,14 +28,14 @@ def test_mapping_file_exists() -> None: assert mapping_path.exists(), f"Mapping file missing: {mapping_path}" -def test_mapping_contains_all_10_questions() -> None: +def test_mapping_contains_all_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}" diff --git a/tests/test_generate_context.py b/tests/test_generate_context.py index 0f7a7a2..0b577c4 100644 --- a/tests/test_generate_context.py +++ b/tests/test_generate_context.py @@ -84,11 +84,13 @@ class TestGenerateContextFiles: mapping_path = root / "context/discovery-context-mapping.md" assert mapping_path.exists() - def test_mapping_covers_all_10_questions(self): - """All 10 core questions should have mappings.""" + def test_mapping_covers_all_questions(self): + """All core questions should have mappings.""" from rdb_discovery.generate_context import CONTEXT_MAP + from rdb_discovery.templates import CORE_QUESTIONS - for i in range(1, 11): + expected_count = len(CORE_QUESTIONS) + for i in range(1, expected_count + 1): qid = f"Q-{i:03d}" assert qid in CONTEXT_MAP, f"Missing mapping for {qid}" @@ -194,11 +196,13 @@ class TestContentPreservation: class TestContextMapCompleteness: """Tests for mapping document completeness.""" - def test_all_10_questions_mapped(self): + def test_all_questions_mapped(self): """Every core question should have a mapping entry.""" from rdb_discovery.generate_context import CONTEXT_MAP + from rdb_discovery.templates import CORE_QUESTIONS - expected_ids = {f"Q-{i:03d}" for i in range(1, 11)} + expected_count = len(CORE_QUESTIONS) + expected_ids = {f"Q-{i:03d}" for i in range(1, expected_count + 1)} mapped_ids = set(CONTEXT_MAP.keys()) assert expected_ids == mapped_ids, f"Missing mappings: {expected_ids - mapped_ids}"