DataArt/artisyn-implementation-harness / skills/implementation-harness
implementation-harness
FlaggedInstall the portable AI-dev harness, rebuild its operational graph standalone, harvest project skill improvements into its canonical templates, package direct canonical edits into a portable bundle, or apply canonical updates to an existing project. Use /implementation-harness launch, /implementation-harness reindex-graph, or /implementation-harness patch harvest|prepare|apply.
canonical/skills/design/references/04-research.md
View on GitHub# Research stage
Apply `{{provider:skills_root}}/design/patterns/metrics.md`; this stage's metrics unit is
`--stage research`. First action, at Step 1: `stage start --stage research`.
Follow the pattern's wait, check, and exit commands for everything after. When
this reference is used only as a correction recipe within another active
stage, retain that stage's metrics ownership.
Resume detection and stage tracking live in `{{provider:skills_root}}/design/SKILL.md`. It
produces a neutral, exhaustive options list โ 3 to 5 alternatives with industry
references. **No recommendation is made here.** Judgment lives in Evaluate. Output:
`design/01 Research.md`.
> โ ๏ธ Follow every step in order. Do not skip, summarize, or improvise. If you are unsure, ask before deviating.
> ๐ **Session continuity:** apply `{{provider:skills_root}}/design/patterns/session-continuity.md`.
## Step 1 โ Read Frame and Evidence
`$DESIGN_DIR` comes from the router's Resume Detection.
Read:
- `design/00 Frame.md` โ the authoritative problem statement and requirements
- `design/Report.md` โ session context, including the `## Context` (subfolder,
track) and `## Evidence` table (every context source Context Gathering
already read) โ reuse this, do not re-read the source docs yourself; context
reading happens once, in Context Gathering
If `design/00 Frame.md` does not exist, tell the developer that Frame must be completed first and stop.
**Multi-decision check:** if `design/00 Frame.md`'s Decisions section lists two
or more decisions confirmed at Frame's dedicated decisions sign-off (Step 2),
apply `{{provider:skills_root}}/design/references/00-decision-router.md` for
the loop boundary (Steps 2โ3 loop, Steps 4โ6 close once) and
`{{provider:skills_root}}/design/patterns/multi-decision-split.md` for the
file-split policy. This was already decided in Frame; do not re-detect or
re-ask here.
---
## Step 2 โ Delegate to `{{DESIGN_ARCHITECT_AGENT}}` for options research
Before delegating, attempt yourself, from the project root: `node docs/.og/cli.mjs
search --dir . --term <text>` (or `query --dir . --related-to <doc>`) against
`docs/.og/docs-operational-graph.sqlite` to surface related docs. Required
(not best-effort): when the graph is missing, stale (see `references/reindex-graph.md`'s Staleness check), or the call errors, fall
back to grep/glob over `{{DESIGN_DOCS_ROOT}}` for the same information โ
either way, never let this block research. This runs here, not inside the
delegation below: `{{DESIGN_ARCHITECT_AGENT}}` can resolve to a read-only
agent with no shell access (`@product-architect` on the Product track), so
the query must be the orchestrator's own step, with whatever it surfaces
folded into the delegation's context.
Delegate to `{{DESIGN_ARCHITECT_AGENT}}` with **explicit constraints**:
- Read relevant context docs under `{{DESIGN_DOCS_ROOT}}`, plus whatever the graph query above surfaced
- Produce **3 to 5 distinct options** โ include at least one "do nothing / minimal change" option if valid, and at least one industry-standard approach
- For each option: description, pros, cons, unknowns/risks, at least one industry reference or precedent, and a **colored Mermaid diagram** illustrating the approach (use `classDef` with fill/stroke/color โ no default-grey diagrams)
- **Do not make a recommendation** โ that is Evaluate's job
- Surface open questions that would block evaluation if left unanswered
- **Do not write or edit any files โ return output only**
Once `{{DESIGN_ARCHITECT_AGENT}}` returns, present the options output directly in the console and continue to Step 2b โ the developer confirms both the option set and the OQ classification together in Step 4's sign-off, not here.
**Reiterate paths**, for use from Step 4's sign-off if the developer raises a concern:
- Option set incomplete โ "Reiterate from Research, Step 2 โ re-delegate to `{{DESIGN_ARCHITECT_AGENT}}` with the specific gap: [gap]."
- Requirements scope has changed (new constraint discovered during research) โ "Reiterate from Frame, Step 1 โ re-draft the Problem/Boundaries/Proposed requirements to capture the new constraint."
---
## Step 2b โ OQ triage
Propose a classification for every open question `{{DESIGN_ARCHITECT_AGENT}}` surfaced โ **(V) Viability** โ would the answer disqualify one or more options โ or **(E) Evaluation-input** โ affects cost/detail but not which options survive. See `{{provider:skills_root}}/design/patterns/design-oq-triage.md` for the full two-tier protocol and resolution rules. State your proposed V/E for each with a one-line reason; the developer confirms or corrects it in Step 4's sign-off, not in a separate round.
**Persist the result as Assumptions.** Once triage completes, the answered/classified OQs are a design artifact โ not ephemeral conversation. Fill in the **existing** `## Assumptions` section in `design/Report.md` (pre-created by the report template โ do not add a new `##` heading). Record the full OQ table (question, V/E, answer/status). Without this, Evaluate starts with no written record of what was already decided.
```markdown
_From Research OQ triage ({YYYY-MM-DD})._
| # | Open question | V/E | Answer / status |
| --- | ------------- | --- | --------------- |
| 1 | {question} | (V) | {answer} |
```
---
## Step 3 โ Save 01 Research.md
Apply the docs-writer authoring pattern (`{{provider:skills_root}}/design/patterns/docs-writer-authoring.md`): delegate the write of `design/01 Research.md` (using `{{provider:skills_root}}/design/templates/research.md`, populated with the options from Step 2 and the proposed OQ classifications from Step 2b โ including every option's Mermaid diagram from `{{DESIGN_ARCHITECT_AGENT}}`'s output) to `@docs-writer` using the selected delegation procedure.
Apply the write-confirm pattern (`{{provider:skills_root}}/design/patterns/write-confirm.md`): say "File saved at `design/01 Research.md`."
## Step 4 โ Sign-off
Apply `patterns/phase-sign-off.md`. Present, in one message: the option set (names
and one line each), the proposed OQ classifications with reasons, and the path to
`design/01 Research.md`. Multi-decision: present every decision's option set and
OQs together, one `design/01 Research - {Decision}.md` path each, per
`references/00-decision-router.md` โ still one sign-off, not one per decision.
> "Research drafted at `design/01 Research.md` โ {N} options, {M} OQs proposed as
> {X} Viability / {Y} Evaluation-input. Good to go, or what should change?"
`report`, then `wait start --reason approval --detail "Awaiting research sign-off"`.
**Stop and wait.** On approval, record the acceptance check
(`--name "Research sign-off"`, `--source developer`); without it `stage complete`
is refused. On approval, persist the confirmed OQ classification into the
**existing** `## Assumptions` section in `design/Report.md` (pre-created by the
report template โ do not add a new `##` heading):
```markdown
_From Research OQ triage ({YYYY-MM-DD})._
| # | Open question | V/E | Answer / status |
| --- | ------------- | --- | --------------- |
| 1 | {question} | (V) | {answer} |
```
Rework: apply the Step 2 reiterate path, present again.
## Step 5 โ Report
Update `design/Report.md`:
- Phase tracker: `๐ฏ Context Gathering โ
ยท ๐ Ceremony โ
ยท ๐ Frame โ
ยท ๐ Research โ
ยท ๐ Evaluate ๐ ยท ๐ฆ Solution โณ ยท ๐ Review โณ ยท ๐ฌ Address Feedback โณ ยท ๐ค Publish โณ ยท ๐ Completion โณ`
- Append to Efforts table: `| {YYYY-MM-DD} | Research | {{DESIGN_ARCHITECT_AGENT}} returned {N} options (<option names>); developer confirmed set complete |`
Then metrics `report`.
## Step 6 โ Commit
Propose:
> `docs({TICKET}): research, {N} options evaluated`
This is a manual-operation sign-off (`patterns/approval-sign-off.md`) โ the
developer runs the commit, never you. `wait start --reason user_input`.
**Stop and wait.** On the reply, check `git log`/`git status`: the commit exists
and the worktree holds nothing from this phase. If not, say what is missing and
wait again. Then `stage complete --stage research`.
๐ Re-read `{{provider:skills_root}}/design/SKILL.md` and resume the router from the next stage.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why โ repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" โ or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself โ your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |