spec-kitty / spec-kitty/spec-kitty

Research planning/task gates reject canonical DR/AR/QR requirements

Open
#3,546 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
1.6k
Forks
165
Avg merge
14h 52m
Merged PRs (30d)
303

Description

## Problem

The canonical research mission cannot pass generic planning/task validation
after a substantive research spec is committed.

## Reproduction 1: setup-plan

Repository: current `origin/main` plus a research mission created with:

```bash
spec-kitty specify docling-graph-kitty-specs --mission-type research --topology single_branch --json
```

Populate and commit the generated canonical `research-spec-template.md`, then
run:

```bash
SPEC_KITTY_ENABLE_SAAS_SYNC=0 SPEC_KITTY_SYNC_DISABLE=1 \
spec-kitty plan --mission docling-graph-kitty-specs-01M0A0FG --json
```

Observed result:

```json
{
"result": "blocked",
"error_code": "SPEC_NOT_SUBSTANTIVE_OR_UNCOMMITTED",
"spec_committed": true,
"spec_substantive": false,
"blocked_reason": "spec.md must be committed AND substantive before setup-plan can run. Populate the Functional Requirements (at least one FR-### row with real description content), commit spec.md, then re-run setup-plan."
}
```

## Reproduction 2: finalize-tasks

After producing a research WP that traces canonical `DR-###`, `AR-###`, and
`QR-###` requirements, run:

```bash
spec-kitty agent mission finalize-tasks \
--mission docling-graph-kitty-specs-01M0A0FG --validate-only --json
```

Observed: the generic requirement-reference parser recognizes only
`FR|NFR|C`, drops the research references, and rejects WP01 for missing
requirements. A supported `migrate backfill-runtime-state` recovery can seed
runtime state, but does not repair the task-finalization contract.

## Why this is a contract mismatch

The built-in research spec template defines a research question,
sub-questions, scope, outcomes, methodology outline, `DR-###` research
requirements, `AR-###` analysis requirements, and `QR-###` quality
requirements. It does not define software-development `FR-###` rows. The
research runtime nevertheless advances through the research lifecycle and its
task surface should preserve those native references.

Therefore valid research artifacts cannot satisfy the generic setup-plan or
task-finalization gates through their own canonical mission-type schema.

## Expected

Planning and task validation should apply mission-type-specific substantive
and requirement-reference rules. For `research`, validate the required
research question/scope plus `DR/AR/QR`; do not require or silently encourage
fake `FR` rows.

## Environment

- macOS arm64
- Python 3.11
- Spec Kitty CLI 3.2.6rc2 from the current repository checkout
- Hosted sync explicitly disabled for the reproduction

## Impact

Blocks the documented research mission path, drops canonical research
traceability, and encourages agents to add fake software-development
requirements or bypass canonical commands.

Contributor guide

Open the contributing guide

Research direction

Start with the `spec-kitty plan --mission ... --json` setup-plan entry point and the `spec-kitty agent mission finalize-tasks ... --validate-only --json` validation path, using the two reproductions in the issue. Read the canonical `research-spec-template.md` and trace substantive-spec and requirement-reference handling. Done means research missions validate their question/scope and preserve DR-###, AR-###, and QR-### references without requiring FR rows.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, tooling
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.