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:
- Upgrade now (recommended) - record
upgrade_now, runupgrade_command, then continue. - Always keep me up to date - record
always, runupgrade_command, then continue. - Not now - record
not_now, then continue. - 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.specifyor/spec-kitty.planstill 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.mdexists (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.mdor filed under<mission_dir>/research/and referenced from it. - Open questions that specify or plan still need to resolve are listed.
04 同仓库更多 Skills
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.
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.
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.
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.
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.
spk-team-tracker
暂无简介