solve-task

name	solve-task
description	Gather disciplined context for solving a task, then hand off to development. Use when the user asks to solve/implement a task ("solve PRI-4", "rag-reviewer:solve-task <key or description>", "реши задачу X"). Reads a keyed task from the reviewer store, pulls related/similar tasks and relevant code, distills a brief, and enters brainstorming. Requires the reviewer MCP server.

Solve Task

Gather the right context for a task, distill it into a brief, then enter the normal development workflow. This skill does NOT plan or implement — it disciplines context-gathering and hands the brief to superpowers:brainstorming (which leads to writing-plans → subagent-driven-development).

Inputs

$ARGUMENTS is either:

• a task key (e.g. PRI-4, matching the board's key_pattern), or
• a free-text description (e.g. "add a logout endpoint").

Pipeline

0. Preflight (index freshness + task-corpus warm-up). Run this BEFORE anything else. First resolve, once, the repo path (git rev-parse --show-toplevel) and the working branch (git branch --show-current; if it is in REVIEW_BRANCHES use it, else the primary branch) — step 3 reuses the same branch for search_codebase.

   Resolve task_board exactly once before any board call. Read the repo .review.yml block: its task_board mapping has priority; an absent block falls back to get_board_config(); an explicit empty task_board: disables board work for this run. Keep the resolved {type, project, key_pattern, create_target, done_target, options} value and reuse this resolved value in Step 1 and every board operation. Never call the deploy fallback when the repo explicitly disables the board.

   1. Base-index freshness. Run uvx --from rag-reviewer reviewer status <path> --branch <branch> --json and read drift for that branch:
      • drift == 0 → continue;
      • drift > 0 → tell the user (in Russian) «индекс отстаёт на N коммитов» and ask for confirmation: reindex now? Yes → delegate to rag-reviewer:sync-codebase (--path <path> --ref <branch>), which reindexes and reports problems, then continue; No → continue on the stale index and record the gap under Constraints / open questions in the brief;
      • drift == null (no clone / no index record) → do not block; note it in the brief.
   2. Problem report — in the style of sync-codebase. If reviewer status fails (Postgres / reviewer MCP / Neo4j unreachable, no index, or uvx missing): tell the user (in Russian) what is missing and the command to fix it. Fail-open — never abort; continue on the stale/unknown index.
   3. Warm the task corpus. Call sync_board(board=<task_board.project or null>, board_type=<task_board.type or null>, provider_options=<task_board.options or {}>, limit=null, purge_orphaned=false) — the resolved task_board.type, task_board.project, and task_board.options from this preflight. If board work is disabled or no board resolves, skip this call and continue board-less. Скоупированный прогрев корпуса своего проекта (PRI-170); пустой project → весь корпус. Incremental (timestamp watermark), cheap when the corpus is warm. Board not configured or status=error → tell the user to run reviewer init, configure the selected registered provider's registry-declared credentials as documented in docs/board-providers.md, run reviewer check, and reconnect MCP; continue board-less.
   4. Summary warmth. Read summaries from the branch object of the Step 0.1 status payload — do NOT probe the summaries tool here. Skip this check if drift == null (no index at all — summaries can't exist). If Step 0.1 produced no payload at all (the fail-open path in Step 0.2), treat that the same as the key being absent below.
      • summaries > 0 → silently continue (no message needed — summaries are warm).

   Decisions: stale → confirmation, never auto (Voyage free tier is 3 RPM / 10K TPM); failures → reported like sync-codebase; sync_board runs incrementally at start; summaries missing → three-way choice (build now / build yourself / skip), read from the status payload instead of dumping every summary into context.

1. Config. Reuse the resolved value from preflight; do not read .review.yml or call get_board_config() again. If no board resolved, continue board-less. For incomplete metadata call get_board_targets(board_type=<task_board.type>, project=<task_board.project>, provider_options=<task_board.options or {}>): select from targets by label, and use option required_for / choices to ask for missing options. Never guess a target or an option and never branch on a board type.

1.5. Choose the brief model (cross-CLI). Building the brief (Steps 2–4: gather + distill) is a light reasoning task over session-less retrieval tools — a top-tier model is overkill and burns tokens. If auto permission mode is active, silently choose the mid tier (Sonnet-class) and continue without asking the user. Otherwise, Ask the user which model tier to use for building the brief, phrasing the choice by tier (cheap / mid / premium) — not by concrete model names — so it works across CLIs (Claude Code, Codex, Gemini, Cursor, …). Recommend a mid tier (Sonnet-class) as the default (do not recommend Fable — a coarse tier is fine but the brief still needs sound judgment). Talk to the user in Russian. Remember the choice for this run. Fail-open: no answer, a decline, or inability to detect auto mode → use the default tier (or, on Path B below, the session model inline). Never block.

Brief-building unit (Steps 2–4) runs on the chosen model. Steps 2–4 (identify → gather → distill → persist) are non-interactive; run them on the model chosen in Step 1.5:

• Path A — per-subagent model override available: dispatch a subagent on the chosen model to execute Steps 2–4, giving it the reviewer session-less tools (get_task, search_codebase, get_subsystem_summaries, get_task_context, search_tasks, the graph tools, get_pr_diff) plus the harness Read/Bash/Glob/Write (to persist the brief). The subagent returns the brief file path and a short summary (kept / dropped).
• Path B — per-subagent model override unavailable (some CLIs): build the brief inline on the session model, or offer the escape-hatch «switch model / run it yourself» in the spirit of the preflight «Прогрею сам» option (Step 0.4). Note in the report that the brief was built inline.
• Existing-artifacts warn (Step 4, user-facing «warn, don't block»): the orchestrator runs that scan-and-warn before dispatch (a subagent must not prompt the user). It derives the task KEY itself — the same $ARGUMENTS-vs-key_pattern regex match Step 2 opens with (no get_task needed) — so the KEY-based artifact globs run pre-dispatch. When Steps 2–4 run in a subagent, the Step 4 warn is thus orchestrator-only; only the idempotency overwrite-glob stays inside the subagent's persist.
• After the unit returns, the orchestrator appends a marker line to the brief: Собран на: <tier/модель>, режим: subagent | inline — records which model built the brief. The brief_cost token block is best-effort and may miss subagent sidechain tokens (documented limitation).
• Fail-open: an error or empty return from the subagent → the orchestrator finishes the brief inline on the session model. Model choice must never break the pipeline.

2. Identify the task.

   • If $ARGUMENTS matches the board's key_pattern:
     1. Store-first. Call reviewer get_task(key, project=<task_board.project>) — it returns the task's own normalized content ({key, aliases[], title, description, criteria[], status, url}) from the reviewer store, which the preflight sync_board (step 0.3) just refreshed.
        • Hit (a task object with a key): use it directly as the TaskBrief. The task is already indexed (the preflight sync persisted it) — do NOT call index_task. Note in the brief that the task data came from the reviewer store (after sync).
          • Thin criteria (optional, fail-open). The store can return criteria=[]; requirements normally live in description. If it has NO heading matching (?i)(критери|приёмк|acceptance), leave criteria empty and record the gap. Do NOT call index_task.
        • Miss (null / no key) AND a board is resolved: call generic incremental sync_board(board=<task_board.project or null>, board_type=<task_board.type>, provider_options=<task_board.options or {}>, limit=null, purge_orphaned=false), then retry get_task(key, project=<task_board.project>) once. Error or second miss → board-less: treat $ARGUMENTS as the task description and record the gap.
        • Miss AND no board: board-less — treat $ARGUMENTS as the task description.
   • Otherwise: treat $ARGUMENTS as the task description; do not perform external task reads.

   Store-first cuts the double-fetch: the preflight sync_board already pulled the whole board into the reviewer store, and a miss gets one generic incremental sync/retry (fewer LLM tokens and no provider-specific client dependency).

3. Gather context (best-effort, fail-open). Any tool returning a "(… unavailable)" / "(ничего не найдено)" note or an error is non-fatal — continue.

   • Subsystem prior (architectural map). Call get_subsystem_summaries(repo, branch, query="<task title>. <first lines of description>") → top-k relevant subsystems by proximity (top-k vs all is server-side; PRI-167). Use the same as . Fail-open: an empty list / a note / an error is non-fatal — omit the brief section and note the gap. The summary is only a prior — every in the brief still comes from snippets, never from the summary text. If a returned summary has , keep it only as a weak prior, do not use it for structural claims, and prefix its line with . is unknown freshness and gets no marker. For , either omit the item or use exactly this line shape: Do not interpolate its title or summary claims. Omitting a stale summary does not change the directly-informing entries selected for : evaluate every code item solely against the task, independently of whether it corroborates or refutes any stale-summary claim.

Use the session-less tools above.

Branch selection for search_codebase.

4. Distill the solution brief. Write a structured markdown brief whose only job is to seed brainstorming — compact, scannable, nothing the implementer won't act on.

   Relevance filter (adaptive — retrieval is already bounded server-side). Server-side cliff (search_codebase) and rails (search_tasks) already cap retrieval adaptively per task — and search_tasks's score is an RRF rank score (SUM(1/(60+rank)), ≈0.016–0.033), NOT comparable across queries, so never gate on an absolute value (search_codebase exposes no score at all, only result order). So DO NOT re-truncate to a fixed number and DO NOT pad artificially: include EVERY returned item that directly informs the implementation. The keep/drop judgment stays binary (directly-informs), and end each section with (dropped N: reason).

   • Order candidates by result rank (tasks: rank/score; code: rank).
   • No fixed ceilings. Take exactly the directly-informing items the tools returned. Related tasks are bounded by the search rails; the brief lists those that directly inform. Expand the graph (related_symbols/callers/definition) only for the few symbols central to the task.
   • Keep/drop is a binary judgment — include an item ONLY if it directly informs the implementation. Rank/score only sets review order; it is not a numeric gate.
     • ✅ INCLUDE: a symbol/file you will edit or mimic; a task whose PR shows a concrete pattern to follow; a constraint that narrows the approach.
     • ❌ EXCLUDE: a task in the same area but a different mechanism; a file the search surfaced that you won't touch or copy; background you won't act on.
   • Report what you dropped: end the Related work, Relevant code and Test exemplars sections with (dropped N: reason).
   • Dedup related sources by key (linked ∪ similar). «Related work» draws from get_task_context (linked) and search_tasks (similar). Deduplicate by canonical task key before inclusion, matching PRI-N↔ID-N via aliases (one task, two codes). On collision keep the linked entry (richer — carries PR/graph context) and drop the similar duplicate, so a task never appears twice in the brief.

   Brief skeleton — fill it, keep each item to one line:

Failure handling (fail-open)

• No configured task_board / failed generic sync / task not found → board-less: build the brief from search_tasks (if the corpus is warm) + search_codebase + the user's formulation; note the missing task context.
• Neo4j down → get_task_context / index_task graph parts degrade (empty + warning); build the brief from search_tasks + search_codebase.
• Empty task corpus (no prior rag-reviewer:sync-tasks or reviews) → search_tasks is empty; use search_codebase + the user's formulation and note the missing task context.
• Postgres down → search_codebase / search_tasks return empty; build the brief from the user's formulation alone and note the missing task context; still hand off to brainstorming.
• Never abort: with any gap, distill what you have, note the deficit in the brief, and still hand off to brainstorming.
• This skill reads task data only through the reviewer store and generic sync_board/retry. The brief file under docs/superpowers/briefs/ is its only repository write.