AGENT SKILL

spec-kitty.research

Capture discovery findings before specification

License 许可
MIT
最近更新
2026-11-15
Stars
★ 2
Forks
0

01 前言 Front Matter

name
spec-kitty.research
description
Capture discovery findings before specification
user-invocable
true

03 SKILL.md 正文

Startup Upgrade Check

Run this at most once per active agent session before the first Spec Kitty command workflow. If you already ran spec-kitty upgrade --agent-check --json in this session, reuse that result and skip this block. Do not run or announce an upgrade check again for later Spec Kitty commands in the same session. Otherwise, before continuing, run:

spec-kitty upgrade --agent-check --json

If JSON action is none, continue. If action is auto_upgrade, run upgrade_command before continuing. If it fails, tell the user and continue with the current Spec Kitty version. If action is guidance, show upgrade_note briefly, then continue. If action is prompt, ask the user with the host-native question UI when available:

Spec Kitty {latest_version} is available. You are on {installed_version}. Upgrade now?

Use these choices:

  1. Upgrade now (recommended) - record upgrade_now, run upgrade_command, then continue.
  2. Always keep me up to date - record always, run upgrade_command, then continue.
  3. Not now - record not_now, then continue.
  4. Never ask again - record never_ask, then continue.

Record the selected choice before continuing:

spec-kitty upgrade --agent-choice <upgrade_now|always|not_now|never_ask> --agent-latest <latest_version> --json

If no host-native question UI is available, present the same four choices in plain text and wait for the user. In non-interactive hosts, choose not_now and continue.

Path reference rule: When you mention directories or files, provide either the absolute path or a path relative to the project root (for example, <mission_dir>/tasks/). Never refer to a folder by name alone.

In repos with multiple missions, always pass --mission <handle> to every spec-kitty command. The <handle> can be the mission's mission_id (ULID), mid8 (first 8 chars of the ULID), or mission_slug. The resolver disambiguates by mission_id and returns a structured MISSION_AMBIGUOUS_SELECTOR error on ambiguity — there is no silent fallback.

User Input

The content of the user's message that invoked this skill (everything after the skill invocation token, e.g. after /spec-kitty.<command> or $spec-kitty.<command>) is the User Input referenced elsewhere in these instructions.

You MUST consider this user input before proceeding (if not empty).

Goal

This is the mission's discovery step (not the /spec-kitty.specify discovery interview). Capture discovery findings — the facts, decisions, and open questions gathered before a spec exists — so /spec-kitty.specify and /spec-kitty.plan can build on them instead of rediscovering the same ground.

Location

This step runs before a spec or plan exists, on whatever branch your mission's planning artifacts land on — that may be main or any other checkout; there is no branch this step must refuse to run on. Work in the repository root checkout: planning steps need no worktree, and this step creates none. If you need the deterministic branch contract, run:

spec-kitty agent mission branch-context --json

This command reads the current checkout only and takes no --mission option.

Where to record findings

Write directly into <mission_dir>/research.md (that is kitty-specs/<mission_slug>/research.md) — create it if it does not exist yet, or extend it if it does; never truncate or replace existing content. Put any supporting evidence (notebooks, spreadsheets, longer excerpts) under <mission_dir>/research/ and reference each file from research.md.

What to record

  • Decisions you have reached and the reasoning behind each one.
  • Evidence — sources, prior art, data — that backs each decision.
  • Open questions that /spec-kitty.specify or /spec-kitty.plan still need to resolve.

Everything you write here is available to the specify and plan steps; nothing here is regenerated or discarded by them. The plan step's Phase 0 extends this same research.md, it does not replace it.


Research-type missions only

The section below applies only to mission types whose pack ships research.md / data-model.md templates (today: the research mission type). For every other mission type — including software-dev — there is no such scaffold: skip this section, the scaffold command creates nothing by default, and recording findings by hand as described above is the whole step.

On a mission type that does ship those templates, once its plan is filled in you can scaffold the remaining artifacts from the pack's templates instead of authoring them by hand:

spec-kitty research --mission <handle>

This creates research.md, data-model.md, research/evidence-log.csv, and research/source-register.csv from the mission type's shipped templates. It never overwrites an existing, non-empty file unless you pass --force, and it never creates an empty file when no template exists for the mission type.

If this Mission is an owned single-branch checkout (created with --owned-checkout), scaffold into the owned checkout, never the primary:

# Owned single-branch checkouts only; do not run this for a Mission without one.
spec-kitty research --mission <handle> --owned-checkout <owned-checkout-path>

Run from inside the owned checkout the selector is optional — research auto-adopts it — but passing --owned-checkout explicitly is safe from any working directory. Not every authoring command auto-adopts; one that does not resolves the primary checkout, so always render the ownership selector for the authoring commands an owned run invokes.


Success Criteria

  • <mission_dir>/research.md exists (created or extended) and records at least one decision with its rationale, or explicitly states there are none yet.
  • Any evidence you gathered is either inline in research.md or filed under <mission_dir>/research/ and referenced from it.
  • Open questions that specify or plan still need to resolve are listed.

04 同仓库更多 Skills

spec-kitty
spec-kitty/spec-kitty-open-packs

kitty-semi-auto

Use to take a tracker issue or a coherent issue-set through a governed delivery run that works autonomously but pauses to escalate the operator's decisions. Runs BOTH ways — in this session (local) or handed to a fresh cloud runner (cloud) — from one set of standing orders covering orientation, code grounding first, Mission-vs-Ops, the pause-and-escalate contract, brownfield discipline, and the canonical closeout to a draft PR the operator merges. Triggers: semi-auto, semi-auto dispatch, run this semi-automatically, deliver these issues semi-auto, hand this to a cloud runner, dispatch semi-auto.

★ 2
spec-kitty
spec-kitty/spec-kitty-open-packs

kitty-report-debrief

Use when a maintainer asks what happened or what is open ("what landed since Friday", "WTF happened with X", a milestone overview). Collects the facts from GitHub, writes a short branded debrief for named readers, and hands the PDF back without committing it. Triggers: what landed since, WTF happened, debrief the weekend, milestone overview, exec overview of open issues, write up what shipped.

★ 2
spec-kitty
spec-kitty/spec-kitty-open-packs

kitty-mission-from-issue

Use to take one or more GitHub issues through a full governed Mission (spec, plan, tasks, implementation, review) to a green pull request flipped to ready for review, which a maintainer then merges. Triggers: mission from issue, run a mission for this issue, drive issue to PR.

★ 2
spec-kitty
spec-kitty/spec-kitty-open-packs

kitty-land-pr

Use when a ready-for-review pull request needs a maintainer to get it ready to merge. Rebases it, fixes and reviews it, updates its description, changelog and docs, and hands it back without merging by hand. Triggers: land this PR, landing pass, land PR.

★ 2
spec-kitty
spec-kitty/spec-kitty-open-packs

kitty-issue-triage

Use to triage a batch of open GitHub issues on spec-kitty/spec-kitty (default, those opened in the last 7 days). Sets type, priority, domain, parent and milestone, and reports stale, duplicate or clustered issues for an operator decision. Triggers: triage issues, triage the tracker, triage new issues.

★ 2
spec-kitty
spec-kitty/spec-kitty-open-packs

spk-team-tracker

暂无简介

★ 2