Skip to content

Add agentic web research MVP: docs, templates, and researcher mode#104

Draft
PatrickSys wants to merge 1 commit intomainfrom
codex/distill-agentic-research-into-mvp-state-branch-3ixy20
Draft

Add agentic web research MVP: docs, templates, and researcher mode#104
PatrickSys wants to merge 1 commit intomainfrom
codex/distill-agentic-research-into-mvp-state-branch-3ixy20

Conversation

@PatrickSys
Copy link
Copy Markdown
Owner

Motivation

  • Provide a repo-native, evidence-first agentic web research contract and artifacts so research jobs can run with append-only scratchpads, claim-level provenance, and a planner-friendly handoff.

Description

  • Add docs/AGENTIC-RESEARCH-MVP.md to describe the distilled architecture, tradeoffs, and operating contract for an agentic research MVP.
  • Add a report template at distilled/templates/research/agentic-report.md and a long-running trace template at distilled/templates/research/agentic-scratchpad.md for consistent outputs and durable audit trails.
  • Integrate an Agentic Research Mode (MVP) section into agents/researcher.md to enable the new behavior without adding a separate role file and to preserve role-count invariants.
  • Link the new MVP guide from README.md so it appears in the public proof/documentation list.

Testing

  • Ran the project test suite with 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.
  • Fixed the failure by removing the temporary extra role and integrating the mode into agents/researcher.md, then ran the targeted test node --test tests/gsdd.audit-milestone.test.cjs, which passed.

Codex Task

Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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`).
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
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]
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
- Confidence: [verified | likely | uncertain]
- Confidence: [HIGH | MEDIUM | LOW]

Comment on lines +42 to +44
| Claim | Source URL | Accessed date |
|---|---|---|
| [claim] | [url] | [YYYY-MM-DD] |
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
| Claim | Source URL | Accessed date |
|---|---|---|
| [claim] | [url] | [YYYY-MM-DD] |
| Claim | Source URL | Confidence | Accessed date |
|---|---|---|---|
| [claim] | [url] | [HIGH | MEDIUM | LOW] | [YYYY-MM-DD] |

Comment thread agents/researcher.md
Comment on lines +95 to +97
Use templates:
- `distilled/templates/research/agentic-report.md`
- `distilled/templates/research/agentic-scratchpad.md`
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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

Suggested change
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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant