Runtime compatibility (read first)

These instructions apply to Claude Code, Codex and DeepSeek Harness (dsh). Resolve CYCLER_ROOT from the environment, CLAUDE_PLUGIN_ROOT, or this skill's directory (../..). CLAUDE_PLUGIN_ROOT in the legacy instructions below is a compatibility alias for that root; CLAUDE_CODE_SESSION_ID may be replaced with CYCLER_SESSION_ID or the current runtime session ID. Use the tools available in your runtime; ToolSearch is not a prerequisite for research or Linear.

/workflow-research — investigation whose deliverable is a decision

/workflow-feature is for changing code. This is for the issues where the output is a recommendation — the RESEARCH: issues on the APL board, "should we use X", "what is our exposure to Y".

Running those through /workflow-feature is waste: no contract to write, nothing for gate.sh to gate, no diff to audit or review. Two research runs done this way cost 83k and 117k tokens and produced cited, decisive answers. The same questions through the full harness would have paid for a contract stage, an audit, a gate and a review panel, all of which would have had nothing to judge.

Inputs

An issue key (APL-27), a Linear URL, or a bare question.

1. Do not duplicate — check first

"${CLAUDE_PLUGIN_ROOT}/poller/lin" issue view <KEY>

Read the existing comments before doing anything. A prior run may already have answered this: a rate limit killed an agent mid-session and its recommendation was already posted, so the relaunch produced a second contradicting comment on the same issue and a human had to reconcile them.

• Substantive answer already there → do not re-run it. Either add only what is genuinely missing, or reply saying it already covers the ground. Say which you did.
• Partial answer → extend it, naming what you are adding.
• Nothing → proceed.

1b. Say you started, before you do anything slow

"${CLAUDE_PLUGIN_ROOT}/poller/lin" issue comment list <KEY> | grep -q 'workflow run started' \
  || "${CLAUDE_PLUGIN_ROOT}/poller/lin" issue comment add <KEY> --body "'research' workflow run started in session \`${CLAUDE_CODE_SESSION_ID:0:8}\`."

This is for the humans watching the board. The poller does not read it: it proves a session started from the session's own transcript. A failure here is never a reason not to continue. The grep makes it idempotent; a re-run must not post it twice. Never put HTML comments or hidden markers in a body.

2. Ground it in this repo before reaching for the web

The value of these answers is that they are about this codebase, not the topic in general. Anyone can summarise a topic; only you can say what outcome-store.ts:153 actually does.

• Read what the issue is about — real files, real line numbers.
• State which claims you verified in code and which you assumed. APL-25's most useful output was not the legal summary; it was noticing that config.yaml asks for LinkedIn credentials nothing reads, which fell out of reading the code to describe the tool accurately.
• Web research (ToolSearch → select:WebSearch,WebFetch) is for facts outside the repo: terms of service, prior art, what a library actually does. Cite URL and access date.

3. Decide

A research issue exists because nobody has chosen. Returning a survey leaves it exactly where it was.

• Lead with the recommendation in one sentence.
• Say what to stop doing, not only what to start. "Pick one approach instead of three" means two get deleted, and naming which is the whole job.
• Where you are choosing between real options, say what the loser costs.
• A named gap beats a plausible guess. "I could not find authoritative information on X" is a valid finding and more useful than a confident sentence you cannot support.
• Contradict the issue when the evidence contradicts it. APL-27's premise — that the gate had no Swift coverage — was false, and saying so changed the conclusion. That correction was worth more than the recommendation it came wrapped in.

4. Post it

"${CLAUDE_PLUGIN_ROOT}/poller/lin" issue comment add <KEY> --body-file <file>

Use --body-file for anything long: a body with backticks, newlines and code spans gets mangled through a shell argument.

Structure: recommendation first, then reasoning, then what to stop. Every claim about this repo carries file:line. Every claim about the world carries a URL and a date. Mark inferences as inferred.

4b. Apply the decision to the board — do not stop at a comment

A decision that only lives in a comment leaves the queue stuck: the issues it grounds still carry the old premise and are still blocked by this one. When the research grounds other issues (children, "blocks" relations, or issues it names), do it yourself — nobody else will:

• Rewrite each downstream issue's description so it states the chosen approach, the real file:line touch points, and what NOT to do.
• Fix the blocked-by relations to the order the findings imply; unlink issues that do not really depend on each other.
• File the issues the findings name (stale docs, bugs) — at most 3, each verified.
• Move this research issue to Done. It has no PR, so nothing else closes it, and every issue it blocks stays undispatched until it does.

Do not ask for confirmation — the issue was delegated to you to decide. If a finding truly needs a human (a product call with no evidence either way), say so in the comment, apply everything else, and leave the issue In Review instead of Done.

5. Report

The recommendation in 3-4 sentences, the comment URL, whether you found a prior comment, and your token usage.

Depth

Default shallow: read what the issue names, decide, post. Most research issues are one focused question and a shallow pass answers them for well under 100k tokens.

Go deeper only when the question genuinely spans surfaces — several platforms, several subsystems. /workflow-research <KEY> --deep is that signal. Deep means more reading, not a fan-out of subagents: an agent per sub-question costs a cold start each and returns prose you then have to reconcile. Both research runs that worked were single agents.

Rules

• No code changes. No branch. No PR. If the answer implies a code change, say what the change is and file it as its own issue — do not start writing it.
• Do not run gate.sh or audit.sh. Both judge a diff, and there is no diff. Running them on an empty tree is a check that cannot fail.
• Keep tool output small: read ranges, grep for symbols, never dump whole files. The context you accumulate is re-read on every later turn of your own run.
• File genuinely out-of-scope defects you trip over as Triage issues ("${CLAUDE_PLUGIN_ROOT}/poller/lin" issue create --team APL --title '...' --description-file <file> --state triage), at most 3, each verified. Both research runs found real bugs this way.