Add agentic web research MVP: docs, templates, and researcher mode#104
Add agentic web research MVP: docs, templates, and researcher mode#104PatrickSys wants to merge 1 commit intomainfrom
Conversation
There was a problem hiding this comment.
Code Review
This pull request introduces the 'Agentic Research Mode (MVP)', establishing a decomposition-first agentic loop for complex web research. The changes include new documentation for the MVP architecture, an updated researcher agent contract, and standardized markdown templates for research reports and scratchpads. Review feedback focuses on maintaining consistency with existing confidence scales (HIGH/MEDIUM/LOW) across documentation and templates, ensuring the report template includes the required confidence column in the source index, and explicitly defining output filenames for the generated artifacts.
| ## MVP Operating Contract | ||
|
|
||
| 1. Never publish a recommendation without at least one linked source. | ||
| 2. Mark every major claim with confidence (`verified`, `likely`, `uncertain`). |
There was a problem hiding this comment.
The confidence labels verified, likely, uncertain introduced here conflict with the HIGH, MEDIUM, LOW labels defined in the Researcher role contract (agents/researcher.md, line 53) and used by the Synthesizer (agents/synthesizer.md, line 173). Using inconsistent labels across different research modes will make it harder for downstream agents to process and aggregate findings. Please harmonize these to use the existing HIGH/MEDIUM/LOW scale.
| 2. Mark every major claim with confidence (`verified`, `likely`, `uncertain`). | |
| 2. Mark every major claim with confidence (HIGH, MEDIUM, LOW). |
| ## 3) Recommendations | ||
|
|
||
| 1. [Recommendation] | ||
| - Confidence: [verified | likely | uncertain] |
There was a problem hiding this comment.
To maintain consistency with the Researcher role contract and the Synthesizer expectations, the confidence labels should use the established HIGH/MEDIUM/LOW scale instead of the new verified/likely/uncertain labels.
| - Confidence: [verified | likely | uncertain] | |
| - Confidence: [HIGH | MEDIUM | LOW] |
| | Claim | Source URL | Accessed date | | ||
| |---|---|---| | ||
| | [claim] | [url] | [YYYY-MM-DD] | |
There was a problem hiding this comment.
The Source index table is missing the Confidence column, which is explicitly required by the 'Evidence registry' definition in the MVP documentation (docs/AGENTIC-RESEARCH-MVP.md, line 28). Adding this column ensures that every claim is directly associated with its source and its verified confidence level.
| | Claim | Source URL | Accessed date | | |
| |---|---|---| | |
| | [claim] | [url] | [YYYY-MM-DD] | | |
| | Claim | Source URL | Confidence | Accessed date | | |
| |---|---|---|---| | |
| | [claim] | [url] | [HIGH | MEDIUM | LOW] | [YYYY-MM-DD] | |
| Use templates: | ||
| - `distilled/templates/research/agentic-report.md` | ||
| - `distilled/templates/research/agentic-scratchpad.md` |
There was a problem hiding this comment.
While the templates are specified, the instructions do not define the expected output filenames for the resulting artifacts. To ensure consistency and allow downstream workflows to locate these files, please specify the target filenames (e.g., AGENTIC-REPORT.md and SCRATCHPAD.md) and their locations (e.g., .planning/research/ or the phase directory).
| Use templates: | |
| - `distilled/templates/research/agentic-report.md` | |
| - `distilled/templates/research/agentic-scratchpad.md` | |
| Write output files (e.g., AGENTIC-REPORT.md and SCRATCHPAD.md) using templates: | |
| - distilled/templates/research/agentic-report.md | |
| - distilled/templates/research/agentic-scratchpad.md |
Motivation
Description
docs/AGENTIC-RESEARCH-MVP.mdto describe the distilled architecture, tradeoffs, and operating contract for an agentic research MVP.distilled/templates/research/agentic-report.mdand a long-running trace template atdistilled/templates/research/agentic-scratchpad.mdfor consistent outputs and durable audit trails.Agentic Research Mode (MVP)section intoagents/researcher.mdto enable the new behavior without adding a separate role file and to preserve role-count invariants.README.mdso it appears in the public proof/documentation list.Testing
npm test --silent, which initially failed due to an extra role file increasing the expected role count; the failure was diagnosed as the role-count invariant.agents/researcher.md, then ran the targeted testnode --test tests/gsdd.audit-milestone.test.cjs, which passed.Codex Task