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 _spec.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 spec ceremony. Do not use for formal spec authoring with grill and ADR review gates (use cy-create-spec), decomposing an already-approved spec (use cy-create-tasks), or executing the generated tasks (use cy-execute-task).
argument-hint: "[slug] [research-prompt] [auto]"
---

# Research Issues

Turn a research question into an executable Compozy task suite. Pipeline:
**scout → parallel explorer analyses → synthesis → lite spec → 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 `_spec.md` (step 5)                    | `references/spec-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/spec-lite-template.md` — the full `_spec.md` template (sections 1-10 incl.
  Compozy 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 spec.
   - 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
     spec and task files.

5. **Author `_spec.md` (lite).**
   - **STOP. Read `references/spec-lite-template.md` in full before writing the spec.**
     Fill every section it defines — the Compozy 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, spec, 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.
- **Spec duplication.** Tasks reference spec 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`).