T-KDZ9-capability-structural-kind-regrade

Status: closed/done · Impact: medium · Complexity: medium

Goal

Capability schema v2 (T-2KK8-capability-kind-grains-and-locations, PR #843) added the optional structural kind, but the migration deliberately left it unset on all 20 instances — the corpus is audience-split but ungraded. The SDF capability graph (Tier B in the UI-consolidation plan) needs grains to render anything beyond monochrome nodes.

Today

Location	Role today
apps/sdlc/lib/model/entities/capability/definition.md	Documents the 11 structural grains and the rule that kind grades structure, never audience
apps/sdlc/lib/model/entities/capability/schema.ts	Schema v2 — kind is an optional 11-grain enum, absent means ungraded
docs/planning/capabilities/	20 instances, all schema v2 with audience: set and kind: unset
apps/sdlc/desktop/docs/ui-consolidation-plan.md	Tier B capability-graph work gates on grains being assigned

Proposed

Every file matching docs/planning/capabilities/C-*.md carries a structural kind: chosen from the 11-grain table, graded from the instance’s own body (Summary, Underlying implementation, and locations[] anchors), with a one-line rationale per instance in the PR body. Instances where the grade is a close call get need_human_review: true so review attention lands where it is needed.

Approach

1. Read the Structural grains section of apps/sdlc/lib/model/entities/capability/definition.md — the grain table plus the audience-vs-structure rule.
2. Grade each instance from its own body. All 20 instances are schema v2 after PR #843, so this is one uniform pass — no pre-migration shapes to tolerate.
3. Grading guidance: a tree root naming a product-scale ability leans system; an importable lib/package leans module; step-sequenced behavior leans workflow; state-holding corpora lean datastore; bridges and shims lean adapter; regenerated artifacts lean generated; single rendered surfaces lean page. When torn between two grains, prefer the one matching what the locations[] anchors actually point at, and set need_human_review: true on that instance.
4. Edit each file’s frontmatter, placing kind: next to audience:; validate each with sdlc entities validate (the validator owns key shape and placement complaints).
5. Run sdlc entities audit over the corpus, then sdlc docs generate and stage its regen output — the docs-drift gate requires it.
6. Compose the PR body table: instance, grain, one-line rationale, and an uncertainty mark wherever need_human_review was set.

Files to touch

Location	Kind	Change
docs/planning/capabilities/C-*.md	modify	Add kind: to each instance’s frontmatter

Acceptance criteria

• AC-1: command grep -L '^kind:' docs/planning/capabilities/C-*.md returns no files — every instance carries a kind: line.
• AC-2: every kind: value across docs/planning/capabilities/C-*.md is one of the 11 grains and sdlc entities audit exits green over the corpus.
• AC-3: sdlc docs generate --check passes on the branch.
• AC-4: the PR body lists all 20 instances with grain and one-line rationale.
• AC-5: the uncertain set matches both ways — the instances marked uncertain in the PR-body table are exactly those listed by command grep -l 'need_human_review: true' docs/planning/capabilities/C-*.md.

Out of scope

• Re-parenting, audience: changes, and locations[] edits.
• Adding or removing grains, or any schema change.
• The Tier B graph rendering itself — UI-thread work that this task unblocks.

Dependencies

• T-2KK8-capability-kind-grains-and-locations shipped the grain vocabulary and migration (closed via PR #843) — satisfied.

Discovery context

• T-2KK8’s Out of scope explicitly deferred regrading to a follow-up triage. Donor-corpus stats (component 22, module 20, subsystem 13 of 76 graded capabilities) suggest most instances land in a few grains.

Post-mortem

Captured by /sdlc:task-work on 2026-07-18. PR: pending.

Acceptance criteria coverage

• AC-1: auto — command grep -L '^kind:' docs/planning/capabilities/C-*.md returns empty (all 20 carry kind:).
• AC-2: auto — every kind: is one of the 11 grains; sdlc entities audit exits 0 (0 drift) over the corpus.
• AC-3: auto — sdlc docs generate --check exits 0 (drift: []); kind: does not alter index/glossary/references, so no regen output.
• AC-4: agent-manual — full grading table (20 rows: grain + one-line rationale + uncertainty) composed for the PR body.
• AC-5: auto — the uncertain set (C-0001, C-0007, C-409J, C-D2GO, C-HRNS) exactly equals command grep -l 'need_human_review: true' docs/planning/capabilities/C-*.md.

What worked

• The 11-grain table plus the audience-vs-structure rule in definition.md gave clear grading criteria; the corpus clustered into a few grains (workflow 9, component 7, system 2, module 1, adapter 1) as the donor stats predicted.
• sdlc entities audit and docs generate --check confirmed the frontmatter edits were schema-clean with no regen fallout — a fast, deterministic verification loop for a 20-file judgment pass.

Friction and automation gaps

• All 20 instances arrived with need_human_review: true (leftover from the v2 migration). AC-5’s bijection (uncertain rows == need_human_review: true) required flipping the 15 confident gradings to false, repurposing the flag from “ungraded” to “close-call grade”. This curation isn’t in ## Files to touch but is mandated by AC-5 — a task that grades into a confidence field should state up front how pre-existing flag values are reinterpreted.
• Two tree roots split by realization: C-0001 → system (spread across many skills/ops) vs C-D2GO → module (a single importable package). The “tree root leans system” heuristic alone would mis-grade the package-realized root; the locations[]-anchor tiebreak (grade by what the anchors point at) was load-bearing.

---

← Back to Tasks