cy-research-issues

name

cy-research-issues

description

Runs a multi-agent research pass over the codebase (and optional competitor sources under .resources/) and converts the findings into an executable Compozy task suite: seven-section analysis documents, a lightweight _techspec.md, and task_NN.md issue files wired into a compozy.tasks/v2 _tasks.md graph, each carrying evidence, competitor references, and unit/integration/e2e test plans so cy-execute-task can run them directly. Use when auditing a subsystem, investigating a bug class, or turning improvement research into a runnable backlog without the interactive PRD/TechSpec ceremony. Do not use for PRD creation (use cy-create-prd), formal TechSpec authoring with ADR review gates (use cy-create-techspec), decomposing an already-approved spec (use cy-create-tasks), or executing the generated tasks (use cy-execute-task).

Research Issues

Turn a research question into an executable Compozy task suite. Pipeline: scout → parallel explorer analyses → synthesis → lite techspec → issue-tasks → graph → validate. The output directory is .compozy/tasks/<slug>/ and its task files are directly consumable by /compozy / cy-execute-task — same parser contract as cy-create-tasks output.

Required Reading Router

Match the current phase to the row. Read the listed file in full before producing that phase's output. They are not appendices — they are load-bearing. Inline content in this SKILL.md is a pointer, not a substitute.

Phase	MUST read
Dispatching or resuming explorer agents (step 3)	references/explorer-dispatch.md
Authoring _techspec.md (step 5)	references/techspec-lite-template.md
Generating task_NN.md files + _tasks.md (step 7)	references/issue-task-template.md

Reference Index

• references/explorer-dispatch.md — explorer agent contract, the seven-section analysis schema, the dispatch prompt template, and the failure/resume protocol for agents killed mid-run.
• references/techspec-lite-template.md — the full _techspec.md template (sections 1-10 incl. AGH Impact Audit and Web/Docs Impact) plus authoring rules (YAGNI, Open Decisions instead of ADR ceremony).
• references/issue-task-template.md — the complete task_NN.md template merging issue DNA with the executable contract, the parser rules, the _tasks.md graph manifest contract, complexity criteria, and test-plan rules.

Required Inputs

• Slug — names the .compozy/tasks/<slug>/ directory.
• Research prompt — the question/goal: bugs to investigate, surfaces to audit, competitor behavior to copy. Concrete symptoms ("returning to a live session shows a blank thread") produce better analyses than abstract goals.
• Optional: competitor directories under .resources/<repo>/ to include as reference slices.
• Optional: auto — skip the single approval checkpoint (step 6) for unattended runs.

Hard Rules

• This skill is analysis + authoring only. Never modify production code, never execute the generated tasks.
• Explorer analyses run through compozy exec with GLM 5.2 via the pi harness (parallel, background) — NOT the runtime's native Agent tool. Each compozy exec is a self-contained, scoped-write dispatch that writes exactly one analysis file. The exact command, the model/harness rules (GLM via pi; never opencode; Opus override for the hardest slices), and the failure protocol live in references/explorer-dispatch.md.
• Every generated task file MUST satisfy the parser contract and carry a ## Tests section with Unit, Integration, and E2E categories — the contract lives in references/issue-task-template.md, not here.
• Do not mark the skill complete until compozy tasks validate --name <slug> exits 0.

Workflow

1. Preflight (lightweight).

   • Read .compozy/config.toml; if it defines [tasks].types, use that list for task type values, otherwise use the defaults (frontend, backend, docs, test, infra, refactor, chore, bugfix).
   • Read docs/_memory/standing_directives.md and skim docs/_memory/lessons/README.md for entries matching the research domain. Cite applicable directives/lessons in the techspec.
   • If .compozy/tasks/<slug>/analysis/ already contains the analyses for this research (resumed run), reuse them and skip steps 2-4.

2. Scout and slice.

   • Run fast structural scans (ls, find, grep/glob) to map the territory — do not deep-read files here; that is the explorers' job.
   • Divide the research into 4-8 slices. Standard slicing for an improvement research: one slice per competitor repo, one per owned surface layer (UI / client data layer / backend), one end-to-end trace per reported bug class, one comparative/mapping slice when copying competitor design. Drop slices that do not apply; add domain-specific ones that do.
   • Each slice gets: a number NN, a kebab slug, a single question, primary source paths, and the target file analysis/NN_analysis_<slice-slug>.md.

3. Dispatch explorers via compozy exec (GLM 5.2 / pi).

   • STOP. Read references/explorer-dispatch.md in full before launching any explorer. It contains the scoped-write contract, the compozy exec command and model/harness rules, the seven-section schema every analysis must follow, the dispatch prompt template, and the failure/resume protocol. Do not improvise dispatch prompts from memory of this file.
   • Write one self-contained prompt file per slice from the template, then background one compozy exec --ide pi --model openrouter/z-ai/glm-5.2 --prompt-file <slice-prompt> per slice (parallel). Wait for every process to exit before synthesis. Escalate a slice to --ide claude --model opus only when it demands maximal citation precision (see the reference).
   • On any non-zero exit or contract violation, apply the reference's failure protocol (re-dispatch the slice with the contract restated).
   • Read each analysis as it lands; note cross-slice contradictions to resolve in synthesis.

4. Synthesize analysis/summary.md.

   • Lead with root-cause chains for every reported bug (numbered causes, each citing path:line evidence from the analyses).
   • State the design verdict when competitors were analyzed (what to copy, what to reject, where the project should deliberately diverge).
   • End with a table mapping each analysis document to its top value, and a pointer to the techspec and task files.

5. Author _techspec.md (lite).

   • STOP. Read references/techspec-lite-template.md in full before writing the techspec. Fill every section it defines — the AGH Impact Audit and Web/Docs Impact sections are mandatory, and contested decisions go to its Open Decisions section instead of blocking on interactive rounds.
   • This is the reference document cy-execute-task reads for implementation guidance — carry root causes, target architecture, delete targets, and sequencing, all evidence-linked.

6. Checkpoint (skip when auto).

   • Present the proposed task breakdown: titles, type, complexity, dependency edges, and the wave grouping. One message, one approval.
   • Use the runtime's interactive question tool and wait. Incorporate feedback and re-present until approved. Do not re-litigate the analyses — only the breakdown is under review.

7. Generate the task suite.

   • STOP. Read references/issue-task-template.md in full before writing any task file or _tasks.md. It is the single source of truth for the file template, parser rules, graph manifest contract, complexity criteria, and test-plan rules. Gist tripwires only:
     • task_NN.md naming, frontmatter = status/title/type/complexity only, dependencies only in _tasks.md (compozy.tasks/v2, acyclic).
     • Every task carries Problem & Evidence + Expected Behavior (issue DNA) AND Subtasks, Deliverables, Tests (Unit/Integration/E2E), Success Criteria (executable contract).
     • Test cases name specific inputs/conditions and the canonical owning suite.
   • Derive test plans from the analyses; keep tasks independently implementable — if two tasks are tightly coupled, merge them or extract the shared piece into a dependency task.

8. Validate.

   • Run compozy tasks validate --name <slug> (read-only check). Fix reported issues and re-run until it exits 0.

9. Report.

   • Print the deliverable tree, the suggested execution order, and the exact follow-up command for execution (e.g., /compozy <slug>). State explicitly that no production code changed.

Anti-Patterns

• Analysis without line numbers. Every claim in analyses, techspec, and tasks cites path:line. An uncited claim is a hallucination gap for the executor.
• Mega-tasks. >7 files or >7 subtasks → split with explicit graph edges.
• TechSpec duplication. Tasks reference techspec sections by name; they never copy its diagrams/interfaces.
• Silent scope caps. If slices, analyses, or issues were dropped for budget, say so in the report — never imply full coverage.

Error Handling

• Explorer failures (non-zero compozy exec exit or stalled slice) → follow references/explorer-dispatch.md §Failure recovery (re-dispatch the slice; escalate to Opus after two GLM failures). If every slice stalls with zero output, confirm dispatch used --ide pi (not opencode) and that ~/.pi/agent/auth.json holds the OpenRouter key.
• Analyses contradict each other → resolve in synthesis with evidence, or mark UNCONFIRMED with the verification step the executor must run first.
• compozy tasks validate keeps failing on the graph → re-check the manifest against references/issue-task-template.md §Graph Manifest before touching task content.
• User rejects the breakdown at the checkpoint → incorporate all feedback before re-presenting; never write task files from an unapproved breakdown (unless auto).