spec-kitty / spec-kitty/spec-kitty

retrospect category diagnosis: robustness + docs follow-ups (from #3537 landing review)

Open
#3,551 0 comments 0 reactions 0 assignees View on GitHub
tech-debt
Dominant language
Python
Stars
1.6k
Forks
165
Avg merge
14h 22m
Merged PRs (30d)
343

Description

Follow-up hygiene surfaced by the adversarial review during the #3537 landing pass. #3537 folded the one MAJOR (proposal vs finding allow-list selection); these are the non-blocking remainder, collected here so they are not lost.

## 1. Replace the substring discriminator with a typed error boundary (MINOR)

`agent_retrospect.py` decides which category allow-list to append by string-matching the exception message: `"category is invalid" in detail` then `"proposals[" in detail`. That couples the CLI to exact wording produced deep in `retrospective/reader.py` (`_validate_gen_finding` / `_validate_gen_proposal`). A reword there would silently drop or mis-pick the allow-list, caught only by the two targeted tests.

Robust fix: have the reader raise a typed `SchemaError` carrying structured fields (e.g. `field="category"`, `scope="finding"|"proposal"`, `allowed=`) so the CLI selects the allow-list from data, not prose. This would subsume the landing fold's substring logic entirely.

## 2. Document the finding & proposal category enums (NOTE — docs gap)

The allowed categories are now surfaced to users in an error message but are enumerated nowhere in `docs/`. `docs/api/retrospective-schema.md` describes the finding shape but never lists the `category` enum, and no doc lists the proposal set. Natural home: add both enums to `docs/api/retrospective-schema.md` so authors hand-editing a retrospective don't have to read `reader.py`.
- Finding: `process, tooling, spec_quality, review_loop, design, implementation, doc, other`
- Proposal: `glossary, drg, doctrine, tooling, process, other`

## 3. Reconcile the roadmap's #1239 framing (NOTE)

`docs/plans/3-2-x-milestone-roadmap.md:386` lists #1239 as "retrospect synthesize rejects its own create records" — the same misconception #3537's body debunks (`create` writes a valid record; `synthesize` consumes it; the real fault was hand-authored categories). The roadmap line now carries a framing the code disproves; worth reconciling #1239's wording.

Refs: #3537, #3533. Related deferred half of #3533 (legacy retrospective path in mission-review skill) is already tracked by #2961.

Contributor guide

Open the contributing guide

Research direction

Start with agent_retrospect.py and retrospective/reader.py, especially _validate_gen_finding and _validate_gen_proposal, then run the two targeted tests mentioned in the issue. Review docs/api/retrospective-schema.md and docs/plans/3-2-x-milestone-roadmap.md: done means category selection no longer depends on exception wording, both enums are documented, and the #1239 framing is reconciled.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, documentation, tooling
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.