spec-kitty / spec-kitty/spec-kitty
retrospect category diagnosis: robustness + docs follow-ups (from #3537 landing review)
- 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
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