spec-kitty / spec-kitty/spec-kitty

Docstring-vs-code drift recurs because nothing enforces DIRECTIVE_037 — build the mechanism and update implementer/reviewer guidance

Open
#4,440 0 comments 0 reactions 0 assignees View on GitHub
design-spike doctrine priority:P2 reliability tech-debt
Dominant language
Python
Stars
1.6k
Forks
165
Avg merge
14h 52m
Merged PRs (30d)
303

Description

## Problem

A behaviour change lands; the docstring or comment describing the **old** behaviour is never swept. The code is correct and the prose beside it is a lie — which is worse than no prose, because a reader trusts it.

[DIRECTIVE_037 (Living Documentation Sync)](../blob/main/.kittify/) already mandates the behaviour. It is being ignored, and nothing enforces it, so it recurs. Four live instances are linked as sub-issues of this one; each is a one-line fix, and each was found by a squad reviewer reading the code, not by any gate.

The individual fixes are not the cost. **The recurrence is the cost** — this is a defect class that should be closed by construction (DIRECTIVE_043), not point-fixed a fifth time.

## Observed shapes

Worth designing against these specifically, since they are what actually occurs:

1. **A docstring names a pinned version that has since moved.** `zeitgeist_bridge._first_non_printable_attr` cites the `spec-kitty-events` 8.2.0 pin and an encode-side check "in flight" that shipped in 9.1.6 (#4318).
2. **A docstring asserts an exclusion or invariant that a later change abolished.** `registry.py`'s `resolve`/`resolve_local` still describe a routing-catalog project-layer exclusion that #4128 removed; the two catalogs now coincide (#4156).
3. **A docstring overclaims a guarantee the code does not make** (#4038).
4. **A docstring states a contract every caller violates.** `promote_activations`' docstring promises the built-in corpus; every caller passes `default.yaml` (#4400).

Shapes 1 and 4 are mechanically detectable. Shape 2 is detectable when the docstring names a symbol or issue number. Shape 3 generally is not.

## What this issue must deliver

1. **A durable enforcement mechanism.** Design is open — this is deliberately a design issue, not a ready-to-implement one. Candidates worth evaluating rather than assuming:
- a check that any version string appearing in a docstring matches the corresponding pin in `pyproject.toml` / `uv.lock` (closes shape 1 outright);
- a check that symbols named in docstrings still resolve (closes much of shape 2);
- a check that a docstring citing a closed issue number is reviewed when that issue closes;
- failing all of those, an explicit reviewer-checklist gate rather than an implicit directive.
2. **Implementer and reviewer guidance updates.** DIRECTIVE_037 exists and is not landing. Whatever changes — the directive's wording, the review contract, the PR template, the squad prompt — should make "did this change invalidate prose next to it?" an actual step rather than an aspiration.

## Scope note

The four linked sub-issues can be fixed independently and immediately; they do not block this. Closing them without landing the mechanism leaves the class open, which is precisely the pattern this issue exists to break.

Contributor guide

Open the contributing guide

Research direction

Start by reading DIRECTIVE_037 under .kittify/ and the four observed drift shapes, then inspect the relevant version pins in pyproject.toml and uv.lock. Evaluate the proposed enforcement approaches and define a mechanism plus implementer/reviewer guidance that makes prose-impact review an explicit step and covers the feasible cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
developer-experience, documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.