Cycle step 2 · /sdd research

Research Phase — validating intent viability

The Research phase (v1.18, §3.5) sits between the Intent Statement and the SPEC. It does not judge the quality of a specification — that is the SQS's role — but answers an earlier question: is this intent achievable, at what cost, with what risks, given the actual code?

Why a step between the Intent and the SPEC

Without a Research phase, the cycle jumps straight from intent to specification: you describe how to build something without ever checking that the terrain allows it. That is the "specs-to-code" anti-pattern: SPECs written in a vacuum, disconnected from existing constraints — established patterns, accumulated debt, real dependencies. The agent discovers those constraints mid-execution, and the session drifts.

Research reverses the order of operations: before a single requirement is written, it maps the code involved, assesses feasibility against the current architecture, and lists the risks and unknowns. The result is archived in .aiad/research/RESEARCH-NNN-<slug>.md, always attached to a parent Intent — a Research is anchored to a human WHY, never to a free-floating idea.

The Discovery — mandatory anchoring in the code

The heart of Research is the Discovery: a map of the impacted code, delegated to a read-only Explore agent to preserve the main session's context budget. Every identified area must be cited as path:line (or evidence: …), together with its existing constraints and the test surface already in place.

## Discovery (code anchoring — Explore agent, read-only)

- Impacted files / areas: src/auth/login.ts:42, evidence: …
- Existing constraints: patterns, debt, dependencies in place
- Existing test surface: test/auth/*.test.ts

The rule is hard by design: without at least one real anchor in the code, the machine verdict stays JNSP (Je Ne Sais Pas — "I don't know"). A Research without a Discovery is an opinion, not an analysis. Any unknown that requires a human decision is recorded as TODO-JNSP: <question> — it never hides behind a confident GO.

A graduated verdict, decided by the human

Research concludes with a verdict line that only an identifiable human can set (human-authorship-check skill). The agent gathers the facts, presents the options, may even offer a recommendation — but never manufactures the decision. The verdict is then hardened by a deterministic scorer: npx aiad-sdd research RESEARCH-NNN.

A CONDITIONAL GO with no conditions listed is rejected by the scorer (JNSP verdict): an implicit condition is an unknown in disguise. Every verdict comes with a confidence level expressed as a percentage — a GO at 60% confidence says something different from a GO at 95%.

The discovery-gate.js hook — a verified prerequisite

Research is not a polite recommendation: it is a mechanically verified prerequisite. The .aiad/hooks/discovery-gate.js hook is consulted by /sdd spec and /sdd exec: without a Research linked to the Intent, with an anchored Discovery and a GO or CONDITIONAL GO verdict, SPEC writing and agent launch are refused.

npx aiad-sdd research <RESEARCH-id>   # exit 0 → OK · 1 → DEFER/NO-GO · 2 → JNSP

JNSP — Missing Discovery for INTENT-NNN
What is missing: a linked Research with an anchored Discovery (path:line)
                 and a GO/CONDITIONAL GO verdict.
Question for the human: run `/sdd research INTENT-NNN` first.

A DEFER or a NO-GO closes the door to /sdd spec durably: it takes a new Research to reopen it. This is consistent with the framework's empiricism — if the context has changed, you demonstrate it again on evidence; you do not recycle a stale verdict.

Proportionality — a safeguard, not bureaucracy

Not every intent deserves a full Research. For a trivial, risk-free intent, the Product Engineer may explicitly bypass the prerequisite — provided the decision is traced in the SPEC. A silent bypass, however, is forbidden: the trace is what distinguishes a deliberate choice from an oversight.

The aiad-sdd proportionality <INTENT-id> command recommends the short path (light Research) or the heavy path (full Research) depending on the risk level. In --guided mode, the grill-me skill probes the GO/NO-GO one question at a time, with a recommendation the human validates or corrects.