rdb-discovery/TASKS.md

# TASKS

## TASK-000 — Bootstrap RDB project standards

Status: Done

Goal: Add the project control files used by RDB agent workflows.

Acceptance Criteria:

- PROJECT_STATE.md exists
- AGENT_HANDOFF.md exists
- .rdb/project.json exists
- context/repository-context.md exists
- TEST_PLAN.md exists
- RUN_LOG.md exists
- README.md explains the structure

## TASK-001 — Implement rdb init

Status: Done

Goal: Create the command that initialises the standard RDB project structure.

## TASK-002 — Generate agent prompts

Status: Done

Goal: Add a command that generates a ready-to-paste implementation prompt for the next Todo task.

Acceptance Criteria:

- `rdb prompt` reads the next Todo task from TASKS.md
- The prompt tells the agent to read README.md, TASKS.md, PROJECT_STATE.md, AGENT_HANDOFF.md, and context/agent-guidelines.md
- The prompt says to implement one task only
- The prompt includes the task title, status, goal, and acceptance criteria
- The prompt includes validation instructions
- The prompt includes reporting instructions
- Add or update tests

## TASK-003 — Improve discovery workflow

Status: Done

Goal:
Improve `rdb discover` so it records structured answers into the discovery ledger.

Acceptance Criteria:

- Ask the 10 core discovery questions
- Record:
  - Question
  - Answer
  - Confidence
  - Follow-up needed
  - Linked decision
  - Linked task
  - Date
- Append answers safely
- Preserve existing discovery history
- Add/update tests
- Update RUN_LOG.md

## TASK-004 — Implement ask-more command

Status: Done

Goal: Add a command that finds weak answers and asks deeper follow-up questions.

Acceptance Criteria:

- command reads discovery-log.md
- low-confidence answers are detected
- follow-up answers are appended to discovery-log.md

## TASK-005 — Task lifecycle commands

Status: Done

Goal:
Allow tasks to be managed from the CLI rather than manually editing TASKS.md.

Acceptance Criteria:

- `rdb start TASK-ID`
  - Marks task In Progress

- `rdb complete TASK-ID`
  - Marks task Done

- Updates PROJECT_STATE.md
- Updates AGENT_HANDOFF.md
- Updates RUN_LOG.md
- Preserves task formatting
- Add/update tests
- Run python -m pytest

## TASK-006 — Agent execution guardrails

Status: Done

Goal:
Detect agent stalls, repeated reads, long reasoning loops, and non-progressing execution.

Acceptance Criteria:

- `rdb guardrails` command exists ✓
- Detects repeated file reads via AGENT_HANDOFF.md analysis ✓
- Detects repeated command entries in RUN_LOG.md ✓
- Flags project files not modified in >48 hours ✓
- Flags missing test run records in RUN_LOG.md ✓
- Checks TASKS.md ↔ RUN_LOG.md consistency ✓
- Produces clear human-readable report with overall status ✓
- All existing tests still pass (33 → 51) ✓
- Guardrail-specific tests added (18 new tests) ✓

## TASK-007 — Improve generated agent prompts

Status: Done

Goal:
Make `rdb prompt` produce smaller, more direct prompts for Claude Code/local LLM agents.

Acceptance Criteria:

- Prompt includes exact known implementation gap when available
- Prompt includes existing test command from CLAUDE.md
- Prompt tells agent not to repeatedly reread unchanged files
- Prompt tells agent to inspect first, then edit
- Prompt limits scope to one small implementation step
- Add/update tests

## TASK-012 — Telemetry foundation

Status: Done

Goal:
Create a minimal telemetry system that can record structured agent activity for future guardrail and analysis features.

Implementation Gap:

The project currently infers agent behaviour from documentation, task files, and run logs.

There is no structured event log showing what actions an agent actually performed during a session.

Acceptance Criteria:

- Create a telemetry module
- Create `.rdb/session-log.jsonl` automatically when recording an event
- Support recording events in JSONL format
- Each event contains:
  - timestamp
  - event_type
  - target
  - details
- Provide a simple public function for writing telemetry events
- Add/update tests

Example Event:

```json
{
  "timestamp": "2026-06-02T12:00:00Z",
  "event_type": "command",
  "target": "rdb prompt",
  "details": {}
}
```

Constraints:

- Do not integrate telemetry into existing commands yet
- Do not modify guardrails yet
- Do not implement dashboards or reporting
- Build the smallest useful telemetry foundation only

Definition of Done:

- Telemetry writer exists
- JSONL file is created correctly
- Events append correctly
- Tests pass
- Documentation updated if required

## TASK-013 — Record CLI command execution

Status: Done

Goal:
Record rdb CLI command execution using the telemetry system.

Implementation Gap:

Telemetry storage exists but no command activity is recorded.

Acceptance Criteria:

- Record command execution events
- Include command name
- Include timestamp
- Add/update tests

Definition of Done:

- All 10 CLI commands record a telemetry event on invocation
- Events have event_type "command" and target "rdb <cmd_name>"
- Timestamps are present in UTC ISO format
- New integration tests added to test_telemetry.py (4 new tests)
- All 75 tests pass

## TASK-014 — Integrate telemetry with guardrails

Status: Done

Goal:
Use structured telemetry data in guardrail analysis.

Implementation Gap:

Guardrails currently rely on heuristics and markdown files rather than actual activity records.

Acceptance Criteria:

- Read telemetry events ✓
- Detect repeated commands ✓
- Detect repeated reads when available ✓
- Fall back gracefully when telemetry is absent ✓
- Add/update tests ✓

Result:

Two new guardrail checks added:

- `check_repeated_commands_telemetry` — uses session-log.jsonl to detect repeated CLI commands (>3x)
- `check_repeated_reads_telemetry` — uses session-log.jsonl to detect repeated file reads (>3x)
  Both integrate into `run_all_guardrails` alongside existing heuristic checks.
  When telemetry data is absent, both return `"ok"` with an informative fallback message instead of failing.

## TASK-015 — Re-centre project purpose

Status: Done

Goal:
Clarify that rdb-discovery exists to help generate and maintain useful project context files for AI-assisted development.

Implementation Gap:

The project now has task, prompt, guardrail, and telemetry features, but the core product purpose needs to be made explicit again.

Acceptance Criteria:

- Update README.md with a clear project purpose
- Explain the core workflow:
  - ask discovery questions
  - capture answers
  - generate context files
  - support agent implementation
- Clarify that telemetry and guardrails support the workflow but are not the main product
- Add/update tests only if required

## TASK-016 — Define standard context file templates

Status: Done

Goal:
Define the standard context files that rdb-discovery should help generate.

Implementation Gap:

There is not yet a clear built-in definition of the context files the tool should produce.

Acceptance Criteria:

- Define templates for:
  - company-context.md
  - development-context.md
  - infrastructure-context.md
  - agent-guidelines.md
  - project-brief.md
  - architecture.md
- Templates include headings and placeholder guidance
- Keep templates simple markdown
- Add/update tests

## TASK-017 — Support task roles in generated prompts

Status: Done

Goal:
Allow tasks to define the agent role used by `rdb prompt`.

Implementation Gap:

Tasks can now include a `Role:` field, but `rdb prompt` still always generates prompts beginning with `You are an implementation agent.`

Acceptance Criteria:

- Parse optional `Role:` field from task markdown
- If `Role:` exists, use it in the generated prompt opening
- If `Role:` is missing, default to `Implementation Agent`
- Add/update tests
- Do not change task execution behaviour

Definition of Done:

- `Role: Architecture Agent` generates `You are an architecture agent.`
- Tasks without a role still generate implementation prompts
- Tests pass

## TASK-018 — Role-based context selection

Status: Done

Role: Implementation Agent

Goal:

Allow `rdb prompt` to select different context files based on task role.

Implementation Gap:

Tasks can now define a role, but every generated prompt still asks the agent to read the same set of files regardless of task type.

Acceptance Criteria:

- Architecture Agent receives architecture-focused context
- Implementation Agent receives implementation-focused context
- Documentation Agent receives documentation-focused context
- If no role exists, use current default file list
- Add/update tests

Definition of Done:

- Context files differ by role
- Existing prompts remain backward compatible
- Tests pass

## TASK-019 — Define discovery-to-context mappings

Status: Done

Role: Architecture Agent

Goal:

Define how discovery answers should be transformed into project context files.

Implementation Gap:

Discovery answers are collected and stored, but there is no documented mapping between discovery questions and the context files they should populate.

Acceptance Criteria:

- Every discovery question maps to one or more context files
- Every discovery question maps to a specific section within those files
- Mapping is documented in markdown
- Mapping is understandable by future agents
- No context generation implementation yet
- Add/update tests if required

Definition of Done:

- Mapping document exists
- 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 mappings

Status: Done

Role: Implementation Agent

Goal:

Generate context file content using the approved
discovery-context-mapping.md document.

Implementation Gap:

Mappings now exist, but discovery answers are not yet transformed into context file content.

Acceptance Criteria:

- Read discovery-context-mapping.md ✓
- Read discovery-log.md ✓
- Populate mapped sections in context files ✓
- Create missing context files safely ✓
- Do not overwrite existing content ✓
- Skip low-confidence answers ✓
- Add/update tests ✓

Definition of Done:

- Discovery answers appear in the correct context files ✓
- Existing content is preserved ✓
- Tests pass ✓ (114 tests, all passing)

Result

Created `src/rdb_discovery/generate_context.py` module with:

- `CONTEXT_MAP`: Rules mapping each of the 10 discovery questions to target context files and sections (body-fill, table-row, or append-new-section strategies)
- `generate_context_files(root, min_confidence)`: Main entry point that reads discovery answers, filters by confidence, applies mapping rules, and writes/updates context files safely
- Three write strategies: TBD-replacement for empty sections, content-appending for existing body-text sections, table-row insertion for risks.md and assumptions.md, and new-section appending when headers don't exist yet

Added `rdb generate` CLI command (accepts `--min-confidence` option).

Fixed a parsing bug in `discovery.py`: escaped pipe characters (`\|`) in discovery answers were creating spurious extra columns during markdown table splitting — now handled with placeholder-based escaping.

Added `tests/test_generate_context.py` with 15 tests:

- Mapping completeness (all 10 questions, all target files)
- Confidence filtering (Low → skipped, High/Medium → generated)
- Body text filling (TBD replacement, existing content append)
- Table row generation (risks.md and assumptions.md formats)
- Content preservation verification
- CLI command availability and error handling
- Missing file creation safety
- End-to-end integration flow

## TASK-021 — Context health report

Status: Done

Role: Implementation Agent

Goal:

Provide a single command that reports the health and completeness of project context.

Implementation Gap:

Context files can now be generated, but there is no way to assess whether sufficient context exists for effective AI-assisted development.

Acceptance Criteria:

- Add `rdb context-status` ✓
- Report expected context files ✓
- Report missing context files ✓
- Report sections still containing TBD placeholders ✓
- Report low-confidence discovery answers ✓
- Display an overall health score ✓
- Add/update tests ✓ (26 tests)

Definition of Done:

- Command runs successfully ✓
- Missing context is reported clearly ✓
- Health score is displayed ✓
- Tests pass ✓ (140 total, all passing)

Result

Created `src/rdb_discovery/context_status.py` module with:

- `_expected_files()` — returns the 18 expected context file paths
- `_check_expected_files()` — checks each file for existence and size
- `_check_tbd_sections()` — scans context files for TBD/TDB placeholders (skips blank lines)
- `_check_low_confidence()` — reads discovery-log.md for low-confidence answers
- `compute_health_score()` — 0-100 score with weighted breakdown (45 pts file completeness, 30 pts no TBDs, 15 pts no low-conf, 10 pts discovery data)
- `context_status()` — orchestrates all checks and returns structured report

Added `rdb context-status` CLI command with:

- Rich table of expected files with presence/absence indicators
- TBD placeholder listing with file, section, and line number
- Low-confidence discovery answer listing with ID and confidence level
- Color-coded health score (green ≥ 70, yellow ≥ 40, red < 40)
- Summary line showing counts

Added `tests/test_context_status.py` with 26 tests across 4 classes:

- TestExpectedFiles — file existence detection
- TestTbdDetection — TBD/TDB placeholder scanning
- TestLowConfidence — low-confidence answer detection
- TestHealthScore — score computation and degradation
- TestContextStatus — structured report verification
- TestCLICommand — CLI registration, output, and edge cases
- TestHealthScoreColor — score boundary validation

All 140 tests pass.

## TASK-022 — Expand discovery coverage

Status: Done

Role: Architecture Agent

Goal:
Collect enough information to populate all standard context files.

Implementation Gap:
Several context files remain mostly placeholders because discovery questions do not collect the information required to populate them.

Acceptance Criteria:

- Review all context templates ✓
- Identify unmapped sections ✓
- Add additional discovery questions where required ✓
- Update discovery-to-context mapping ✓
- Add/update tests ✓

Definition of Done:

- Every major template section has a discovery source ✓
- Discovery-to-context mapping updated ✓
- Tests pass ✓ (140, all passing)

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: Done

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: Done

Role: Documentation Agent

Goal:
Reduce token waste and unnecessary agreement in agent interactions.

Implementation Gap:
Agent guidance does not yet explicitly discourage praise, repeated context reading, task restatement, or unnecessary narrative output.

Acceptance Criteria:

- Update `context/agent-guidelines.md`
- Add objectivity guidance
- Add context-discipline guidance
- Add communication-efficiency guidance
- Add execution-efficiency guidance
- Keep guidance concise and role-neutral
- Add/update tests only if required

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 — Define discovery gap analysis model

Status: Done

Role: Architecture Agent

Goal:
Define how missing or weak project context should be detected and converted into targeted follow-up discovery questions.

Acceptance Criteria:

- Define gap detection rules
- Define gap severity levels
- Define question generation rules
- Define question prioritisation rules
- Define mapping between missing context sections and follow-up questions
- Document the model
- Define the follow-on implementation task
- No implementation

Definition of Done:

- Gap analysis model documented
- Follow-up question model documented
- Example gap-to-question mappings included
- TASK-026 implementation task defined

Result

Created `context/gap-analysis-model.md` (320 lines) as a planning artifact documenting:

1. **Gap detection rules** — 4 rule types (GAP-01 through GAP-04): TBD placeholders, unmapped sections, partial content, near-empty files
2. **Severity levels** — S1 (Critical), S2 (Important), S3 (Low) with assignment criteria per stage and mapping status
3. **Question generation rules** — 6 rules (QG-01 through QG-06): one-gap-per-question, answerable format, section reference, table-column specificity, skip-filled sections, owner-answer alignment
4. **Question prioritisation** — Ordered by severity → file completeness → dependency order → question scope
5. **Gap-to-question mapping table** — 40+ section-level mappings across all 16 template context files (excludes CLI-managed project-level files)
6. **End-to-end example flow** — Step-by-step walkthrough from detection through prioritisation to follow-up generation to regeneration
7. **Edge cases** — Partial sections, acceptable TBDs, new templates, multi-question sections, heading-only files
8. **TASK-026 implementation scope** — CLI command spec (`rdb gap`), module structure, test requirements (~45 tests across 6 categories)

## TASK-026 — Implement discovery gap analysis

Status: Todo

Role: Implementation Agent

Goal:
Implement the approved discovery gap analysis model.

Acceptance Criteria:

- Analyse generated context files
- Detect missing sections
- Generate follow-up questions
- Link questions to missing context sections
- Add/update tests

## TASK-027 — 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-028 — 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-029 — 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