Add agentic web research MVP harness to Workspine #103
+192
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,98 @@ | ||||||
| # Agentic Research Harness (MVP) | ||||||
|
|
||||||
| Use this when the task requires substantial web-enabled research and evidence-driven synthesis. | ||||||
|
|
||||||
| ## 0) Run metadata | ||||||
|
|
||||||
| - Date: | ||||||
| - Operator: | ||||||
| - Query: | ||||||
| - Tier (`light|full`): | ||||||
| - Response format (`short|structured|argumentative`): | ||||||
| - Citation style: | ||||||
|
|
||||||
| ## 1) Decompose prompt | ||||||
|
|
||||||
| Write `prompt-decomposition.json` with: | ||||||
|
There was a problem hiding this comment. To ensure consistency with the directory structure defined in the MVP documentation, the path for the decomposition artifact should be explicitly relative to the research root.
Suggested change
|
||||||
|
|
||||||
| - `sub_questions` | ||||||
| - `entities` | ||||||
| - `required_formats` | ||||||
| - `required_sections` | ||||||
| - `required_section_headings` | ||||||
| - `time_horizons` | ||||||
| - `time_periods` | ||||||
| - `scope_conditions` | ||||||
| - `pipeline_tier` | ||||||
| - `response_format` | ||||||
| - `citation_style` | ||||||
|
|
||||||
| ## 2) Coverage matrix | ||||||
|
|
||||||
| Build `coverage-matrix.md` mapping each significant phrase in the query to decomposition items. | ||||||
|
There was a problem hiding this comment. Explicitly defining the path for the coverage matrix ensures it is correctly located within the .planning/research/agentic/ directory as required by the core artifact specification.
Suggested change
|
||||||
|
|
||||||
| **Gate:** zero `Gap? = YES` rows before moving on. | ||||||
|
|
||||||
| ## 3) Width sweep | ||||||
|
|
||||||
| Collect broad candidate sources and cluster by theme: | ||||||
|
|
||||||
| - canonical/primary | ||||||
| - secondary synthesis | ||||||
| - dissenting or contradictory evidence | ||||||
| - recent updates | ||||||
|
|
||||||
| Log results in `width-sweep.md`. | ||||||
|
There was a problem hiding this comment. Defining the explicit path for the width sweep log maintains alignment with the artifact organization specified in the MVP documentation.
Suggested change
|
||||||
|
|
||||||
| ## 4) Depth passes | ||||||
|
|
||||||
| Create one note file per major sub-question under `depth-notes/`. | ||||||
|
There was a problem hiding this comment. The depth-notes/ directory should be prefixed with the research root path to prevent the operator from creating it in the repository root, which would violate the artifact organization defined in the MVP spec.
Suggested change
|
||||||
|
|
||||||
| Each file should include: | ||||||
|
|
||||||
| - claims supported | ||||||
| - conflicting evidence | ||||||
| - open uncertainties | ||||||
| - confidence level | ||||||
|
|
||||||
| ## 5) Synthesis draft | ||||||
|
|
||||||
| Write `synthesis.md` with: | ||||||
|
|
||||||
| - thesis | ||||||
| - claim graph | ||||||
| - tensions and tradeoffs | ||||||
| - implications | ||||||
|
|
||||||
| ## 6) Adversarial critique | ||||||
|
|
||||||
| Write `critique.md`: | ||||||
|
|
||||||
| - unsupported claims | ||||||
| - weak evidence links | ||||||
| - alternative interpretations | ||||||
| - overreach risks | ||||||
|
|
||||||
| ## 7) Patch and finalize | ||||||
|
|
||||||
| - log revisions in `patches.md` | ||||||
| - produce `final-report.md` | ||||||
|
|
||||||
| ## 8) Verification | ||||||
|
|
||||||
| Write `verification.md` with pass/fail for: | ||||||
|
|
||||||
| - decomposition completeness | ||||||
| - coverage gap status | ||||||
| - source quality threshold | ||||||
| - citation traceability | ||||||
| - unresolved risk disclosure | ||||||
|
|
||||||
| ## 9) Scratchpad discipline | ||||||
|
|
||||||
| Maintain `scratchpad.md` as append-only notes for long jobs: | ||||||
|
There was a problem hiding this comment. Explicitly defining the path for scratchpad.md ensures it is correctly located within the .planning/research/agentic/ directory as required by the core artifact specification.
Suggested change
|
||||||
|
|
||||||
| - timestamp | ||||||
| - action | ||||||
| - outcome | ||||||
| - next step | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| # Agentic Research MVP for Workspine | ||
|
|
||
| This MVP distills HyperResearch-style decomposition + multi-pass research into a Workspine-native, repo-first flow usable by any developer when web research is enabled. | ||
|
|
||
| ## Goals | ||
|
|
||
| - Add a deterministic, artifact-first **agentic web research harness** to Workspine. | ||
| - Preserve Workspine's existing evidence/verification philosophy. | ||
| - Keep the first version lightweight enough to run today from existing skills. | ||
|
|
||
| ## Architecture (MVP) | ||
|
|
||
| ```text | ||
| query intake | ||
| -> decomposition contract | ||
| -> width sweep (parallel source collection) | ||
| -> depth passes (focused sub-questions) | ||
| -> synthesis | ||
| -> adversarial critique | ||
| -> patch + finalize | ||
| -> verification pack | ||
| ``` | ||
|
|
||
| ### Core artifacts | ||
|
|
||
| All artifacts live under `.planning/research/agentic/`: | ||
|
|
||
| - `scaffold.md` — run config, model/tooling assumptions, citation style. | ||
| - `prompt-decomposition.json` — atomic asks, entities, section contract, tier/format. | ||
| - `coverage-matrix.md` — phrase-to-atomic coverage audit, zero known gaps requirement. | ||
| - `width-sweep.md` — broad source harvest and clustering. | ||
| - `depth-notes/*.md` — deep dives by sub-question. | ||
| - `synthesis.md` — thesis, claims, confidence, tensions. | ||
| - `critique.md` — adversarial reviewer findings. | ||
| - `patches.md` — revision deltas applied after critique. | ||
| - `final-report.md` — publishable output. | ||
| - `verification.md` — evidence gates: source quality, instruction coverage, unresolved risks. | ||
| - `scratchpad.md` — append-only operator log for long-running jobs. | ||
|
|
||
| ## Workflow mapping into Workspine | ||
|
|
||
| This MVP maps to existing workflow primitives instead of introducing a new binary command: | ||
|
|
||
| 1. Use `gsdd-plan` to define research objective/scope in phase plan. | ||
| 2. Execute using the new harness instructions in `.planning/templates/research/agentic-harness.md`. | ||
| 3. Verify with `gsdd-verify` plus research-specific checklist from template. | ||
|
|
||
| ## Tradeoffs considered | ||
|
|
||
| ### 1) Full orchestration engine vs template-first harness | ||
|
|
||
| - **Chosen:** template-first harness. | ||
| - **Why:** lowest integration risk; no new runtime dependency or scheduler needed. | ||
| - **Tradeoff:** less automation than a bespoke orchestrator; more manual operator discipline. | ||
|
|
||
| ### 2) Single-pass writeup vs decomposition-driven pipeline | ||
|
|
||
| - **Chosen:** decomposition-driven pipeline. | ||
| - **Why:** better instruction-following and coverage control. | ||
| - **Tradeoff:** more artifacts and overhead for simple queries. | ||
|
|
||
| ### 3) Maximal source count vs quality-gated source sets | ||
|
|
||
| - **Chosen:** quality-gated source sets. | ||
| - **Why:** avoids noisy synthesis and citation bloat. | ||
| - **Tradeoff:** may miss fringe signals unless explicitly widened. | ||
|
|
||
| ### 4) Purely neutral summary vs adversarial critique pass | ||
|
|
||
| - **Chosen:** adversarial critique required before finalization. | ||
| - **Why:** catches unsupported claims and overconfident framing. | ||
| - **Tradeoff:** extra latency per report. | ||
|
|
||
| ## Operating rules for web-enabled research | ||
|
|
||
| - Prefer primary sources (official docs, papers, filings) where possible. | ||
| - Record retrieval date in artifact headers. | ||
| - Every major claim in `final-report.md` must trace to at least one source in synthesis notes. | ||
| - No unresolved `Gap? = YES` rows in coverage matrix before synthesis. | ||
|
|
||
| ## Definition of done (MVP) | ||
|
|
||
| A research run is done when: | ||
|
|
||
| 1. Required artifacts exist and are non-empty. | ||
| 2. Coverage matrix has zero known gaps. | ||
| 3. Critique findings are either fixed or explicitly accepted with rationale. | ||
| 4. Final report includes clear assumptions, confidence notes, and source list. | ||
| 5. Verification file passes all checklist items. | ||
|
|
||
| ## Integration note: "latest agentic harness" | ||
|
|
||
| For this MVP, "latest harness" is represented as a **pipeline contract** and artifact schema, not a hard-coded external dependency. This keeps Workspine stable while allowing future upgrades to deeper automation in a backward-compatible way. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The AGENTIC-RESEARCH-MVP.md documentation (line 28) specifies scaffold.md as the artifact for run metadata and configuration. This template should explicitly instruct the operator to write the metadata to that file to ensure the artifact is created as expected by the architecture.