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/01-context-gathering.md
View on GitHub# Context Gathering stage
Apply `{{provider:skills_root}}/design/patterns/metrics.md`; this stage's metrics
unit is `--stage context-gathering`. Metrics start in Step 4 below, once the
folder and Report.md exist — not at the top of the stage.
Resume detection and stage tracking live in `{{provider:skills_root}}/design/SKILL.md`.
This stage gathers what the ticket means and identifies which track (Product
or Project — see `{{provider:skills_root}}/design/SKILL.md`'s router callout)
and subfolder this design belongs to — once, read-only — before Ceremony does
any mutation and before
Frame writes anything. The resolved track decides the Stories root the story
folder is created under. It creates the story folder and `design/Report.md`,
but writes no framing content; that is Frame's job.
One stop in this stage: the sign-off in Step 5 on the gathered context. There is
no commit here; the story folder is committed by Ceremony Step 4, after the branch
checkout, so the lifecycle's first commit lands on the feature branch.
> 🔁 **Session continuity:** apply `{{provider:skills_root}}/design/patterns/session-continuity.md`.
## Step 1 — Resolve the ticket or local ID
The argument is a ticket number (e.g. `{{PROJECT_KEY}}-042`), free-form input, or a
direct folder path.
If `$DESIGN_DIR` already came from the router's Resume Detection (a resume, not a
fresh start) and `design/Report.md` already exists, the folder, context, and
Report.md are all already resolved — skip straight to Step 5 (Sign-off).
Otherwise (fresh start): if no tracker ticket is supplied, generate a stable local
ID before creating any files: `DESIGN-YYYYMMDD-XXXX`, where `XXXX` is four
uppercase alphanumeric characters. Check the story folder for a collision; if it
exists, generate a new suffix. Use this ID everywhere a ticket is required,
including the folder name, Report.md, stat.json, branch suggestion, commit
message, and later hand-off. It is a local design identifier, not a claim that a
tracker record exists.
---
## Step 2 — Fetch tracker context _(skip if free-form only)_
If a ticket number was found, invoke `@scrum-master`:
> "Fetch {TICKET}: return summary, description, acceptance criteria, linked {{PROJECT_KEY}} tickets, and any Confluence page URLs."
Then fetch each linked Confluence page directly and extract relevant content
(requirements, specs, design notes). This is a read: do not assign or transition
the ticket here — that's Ceremony's job.
Developer free-form input (from `{{provider:input}}`) takes precedence over tracker
content if they conflict; use the tracker/Confluence as background context and the
known ECs source, and developer input as the primary intent. The fetched summary
also supplies `{name}` for the folder created in Step 4.
**If `@scrum-master` reports a tracker error** (timeout, auth error, or ticket not
found): do not block — continue with developer input only, and ask the developer
to paste the summary/description/ECs manually if nothing else is available.
---
## Step 3 — Resolve design context and read sources
{{DESIGN_CONTEXT_STEP}}
Before reading sources by hand, attempt `node docs/.og/cli.mjs search --term
<text>` (or `query --related-to <doc>`) against `docs/.og/docs-operational-graph.sqlite` to
surface docs already related to this ticket. 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
`docs/` for the same information. Either way, never let this block the stage —
and fold anything the graph (or its fallback) surfaces into Step 4's Evidence
table like any other source.
This identifies, among other fields, the **Stories root** — `{{DESIGN_STORIES_ROOT}}`
— which decides where Step 4 creates the story folder — and the **Architect
agent** — `{{DESIGN_ARCHITECT_AGENT}}` — that Research, Solution, and Publish
delegate to. Identifying Product vs. Project is this stage's responsibility;
no later stage re-asks, re-derives, or hardcodes any of these values — every
stage reference and pattern reads them from `design/Report.md`'s `## Context`
section, resolved here and nowhere else, regardless of deployment mode.
This step also does the lifecycle's one context-reading pass, as part of
the resolution above. Frame, Research, and every later phase read
what was found here from `design/Report.md`'s `## Evidence` table (populated
in Step 4) instead of re-reading the source docs themselves — and it's how
session continuity recaps context after a new session picks the ticket back
up, instead of relying on conversation history that session no longer has.
---
## Step 4 — Create the story folder and Report.md
The title is known now if a ticket number was found (the tracker summary). For
free-form input with no ticket, propose a short title yourself — summarize
the developer's own words, do not ask them to write it. Use it as `{name}`;
it is confirmed, not blocked on, at Step 5's sign-off — if they want a
different title, that is a one-line rework there, not a stop here.
Create the story folder under the Stories root resolved in Step 3:
```
{{DESIGN_STORIES_ROOT}}[{TICKET}] {name}/
design/
```
(`solution/` is created later, by the Solution phase.) This is `$DESIGN_DIR`
(`{{DESIGN_STORIES_ROOT}}[{TICKET}] {name}/design/`) for every subsequent stage
and metrics command.
Create `design/Report.md` now using `{{provider:skills_root}}/design/templates/report.md`,
with `Phase` set to
`🎯 Context Gathering 🔄 · 🚀 Ceremony ⏳ · 📋 Frame ⏳ · 🔍 Research ⏳ · 🏗 Evaluate ⏳ · 📦 Solution ⏳ · 🔎 Review ⏳ · 💬 Address Feedback ⏳ · 📤 Publish ⏳ · 🏁 Completion ⏳`.
Fill in the `## Evidence` table with every source actually read in Step 3 —
one row each: `Source` (file/doc path), `Read at stage` = `context-gathering`,
`Relevant decision or constraint` (what it told you, one line), `Reference/version`
(if applicable). An empty table is only correct when Step 3 genuinely found
nothing relevant, not when the read was skipped.
Initialize design metrics now that Report.md and its directory exist: `init` with
an explicit design `--dir` and the ticket/story identifier, then
`stage start --stage context-gathering`. If `stat.json` already exists,
recover/resume it rather than initializing new history.
---
## Step 5 — Sign-off
Apply `patterns/phase-sign-off.md`. Present, in one message, the findings
gathered across Steps 1–4: the resolved/proposed title, the ticket summary,
the resolved track/subfolder/architect agent, the folder path, and how many
sources Step 3 read into the Evidence table.
> "Context gathered for `{TICKET}` at `design/Report.md`: {one-line ticket summary}.
> Title: {name}. Track: {Product/Project}, subfolder: {resolved subfolder}.
> {N} context sources read into Evidence. Good to go, or what should change?"
`report`, then `wait start --reason approval --detail "Awaiting context-gathering sign-off"`.
**Stop and wait.** On approval, record the acceptance check
(`--name "Context Gathering sign-off"`, `--source developer`); without it
`stage complete` is refused.
Rework — apply the named path, present again:
- Title wrong → rename `{name}` and the folder (git mv if already created), re-save.
- Wrong track, subfolder, or Evidence sources → "Reiterate from Step 3 — re-resolve context and re-read."
- Tracker summary wrong or incomplete → "Reiterate from Step 2 — re-fetch or ask the developer to paste the missing pieces."
## Step 6 — Report
Update `design/Report.md`:
- Phase tracker: `🎯 Context Gathering ✅ · 🚀 Ceremony 🔄 · 📋 Frame ⏳ · 🔍 Research ⏳ · 🏗 Evaluate ⏳ · 📦 Solution ⏳ · 🔎 Review ⏳ · 💬 Address Feedback ⏳ · 📤 Publish ⏳ · 🏁 Completion ⏳`
Then metrics `report`.
## Step 7 — Close
No commit in this stage. `stage complete --stage context-gathering`. Continue to
Ceremony for a full-flow request. For direct entry stop here and say that the story
folder is uncommitted on purpose until `{{provider:invoke:design}} ceremony {TICKET}`
checks out the branch and proposes the first commit.
🔁 Re-read `{{provider:skills_root}}/design/SKILL.md` and resume the router from the next stage (Ceremony).
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 |