From d5002aeae1923e745bdf68c15bfe61683ea4539d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Patrick=20Rossell=C3=B3=20Colom?=
 <74001504+PatrickSys@users.noreply.github.com>
Date: Sun, 3 May 2026 13:35:22 +0200
Subject: [PATCH] Add agentic research MVP docs and scratchpad templates

---
 README.md                                     |  1 +
 distilled/README.md                           |  3 +
 .../prompt-decomposition.json                 |  9 +++
 .../templates/research-agentic/scratchpad.md  | 16 +++++
 docs/AGENTIC-RESEARCH-MVP.md                  | 60 +++++++++++++++++++
 5 files changed, 89 insertions(+)
 create mode 100644 distilled/templates/research-agentic/prompt-decomposition.json
 create mode 100644 distilled/templates/research-agentic/scratchpad.md
 create mode 100644 docs/AGENTIC-RESEARCH-MVP.md

diff --git a/README.md b/README.md
index 2d3ddaf..7218198 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,7 @@ Then pick the first workflow lane that matches your situation:
 - `gsdd-new-project` for greenfield work, fuzzy brownfield work, or milestone-shaped work
 - `gsdd-quick` for a concrete bounded brownfield change
 - `gsdd-map-codebase` first when the repo is unfamiliar, risky, or needs a deeper baseline before choosing a lane
+- `agentic-research` workflow contract for web-enabled decomposition-first research (MVP docs in `docs/AGENTIC-RESEARCH-MVP.md`)
 
 In a terminal, `npx -y gsdd-cli init` opens a guided install wizard. If you installed the package globally, `gsdd init` is the equivalent shorthand:
 
diff --git a/distilled/README.md b/distilled/README.md
index 8cf0d9f..1e0ca00 100644
--- a/distilled/README.md
+++ b/distilled/README.md
@@ -208,6 +208,9 @@ distilled/
       architecture.md
       pitfalls.md
       summary.md
+    research-agentic/
+      prompt-decomposition.json
+      scratchpad.md
     codebase/
       stack.md
       architecture.md
diff --git a/distilled/templates/research-agentic/prompt-decomposition.json b/distilled/templates/research-agentic/prompt-decomposition.json
new file mode 100644
index 0000000..64fa653
--- /dev/null
+++ b/distilled/templates/research-agentic/prompt-decomposition.json
@@ -0,0 +1,9 @@
+{
+  "sub_questions": [],
+  "entities": [],
+  "required_formats": [],
+  "required_sections": [],
+  "required_section_headings": [],
+  "time_horizons": [],
+  "scope_conditions": []
+}
diff --git a/distilled/templates/research-agentic/scratchpad.md b/distilled/templates/research-agentic/scratchpad.md
new file mode 100644
index 0000000..65c056a
--- /dev/null
+++ b/distilled/templates/research-agentic/scratchpad.md
@@ -0,0 +1,16 @@
+# Research Scratchpad
+
+Use this for long-running jobs. Append entries; do not rewrite history.
+
+## Timeline
+
+- YYYY-MM-DD HH:MM UTC — Started run. Objective: ...
+- YYYY-MM-DD HH:MM UTC — Decomposition complete. Notes: ...
+- YYYY-MM-DD HH:MM UTC — Breadth sweep pivot. Why: ...
+- YYYY-MM-DD HH:MM UTC — Depth lane update. Confidence: ...
+- YYYY-MM-DD HH:MM UTC — Critic findings applied. Changes: ...
+
+## Open risks
+
+- Risk:
+- Mitigation:
diff --git a/docs/AGENTIC-RESEARCH-MVP.md b/docs/AGENTIC-RESEARCH-MVP.md
new file mode 100644
index 0000000..e4af07a
--- /dev/null
+++ b/docs/AGENTIC-RESEARCH-MVP.md
@@ -0,0 +1,60 @@
+# Agentic Research MVP (Web-enabled)
+
+This MVP distills the HyperResearch-style decomposition and long-horizon research loop into Workspine-compatible artifacts that any developer can run with web research enabled.
+
+## Scope and outcome
+
+- Adds a reusable workflow contract for agentic research in `.planning/research/`.
+- Enforces prompt decomposition before search.
+- Uses a scratchpad protocol for long jobs to prevent drift.
+- Captures architecture tradeoffs and verification gates so outputs are shippable.
+
+## Architecture (MVP)
+
+1. **Decompose first**
+   - Parse the user request into atomic asks, entities, required sections, horizons.
+   - Emit `prompt-decomposition.json` and heading contract.
+
+2. **Breadth sweep (agentic search)**
+   - Run broad source discovery across primary sources first.
+   - Build a source ledger with relevance and confidence notes.
+
+3. **Depth lanes**
+   - Split into 2-5 focused lanes (methods, evidence quality, counterarguments, implementation implications).
+   - Keep lane notes separate, then synthesize.
+
+4. **Synthesis and adversarial pass**
+   - Produce thesis + evidence chain.
+   - Run a critic pass for missing sections, unsupported claims, and citation gaps.
+
+5. **Delivery package**
+   - Final report + sources + limitations + follow-up experiments.
+
+## Core artifacts
+
+- `.planning/research/scaffold.md`
+- `.planning/research/query.md`
+- `.planning/research/prompt-decomposition.json`
+- `.planning/research/scratchpad.md`
+- `.planning/research/source-ledger.md`
+- `.planning/research/lane-*.md`
+- `.planning/research/draft.md`
+- `.planning/research/final.md`
+
+## Tradeoffs
+
+- **Rigor vs speed:** decomposition + critics improve fidelity but increase latency.
+- **Breadth vs depth:** wider search reduces blind spots but costs tokens/time.
+- **Single-agent vs lane parallelism:** parallel lanes improve coverage but require stronger merge discipline.
+- **Citation density vs readability:** high citation density helps auditability, hurts narrative flow.
+
+## Verification gates
+
+- Structural match against required section headings.
+- Every major claim has at least one source.
+- Explicit unresolved questions and confidence labels.
+- Reproducible scratchpad timeline of major decisions.
+
+## How this integrates with Workspine
+
+Use the reusable templates in `distilled/templates/research-agentic/` and copy them into `.planning/research/` as the starting harness for this MVP.