fix(skills): architecture contradicted itself on stories, so no build passed

[axewilledge]

Symptom

Every project fails the build gate after the design phase, deterministically:

UNCOVERED_STORY: story 1 is in the PRD but no component's design.json lists it in `stories`
UNCOVERED_STORY: story 2 …   (and so on, for every story)

Cause: architecture contradicts itself

It states both:

• the stories enrichment field: "the PRD story numbers this component serves, as an integer array … Claim every story the component actually serves."
• the Recomputed and overwritten bullet: "the component's stories array — the platform restamps it from the design.cell citations, so cite stories in the CELL, never here."

The second is stale, and it's the one that wins, because it's framed as a platform fact — "anything you write there is discarded". An agent that believes the field is overwritten has no reason to fill it, so stories stays empty and the gate refuses every tag.

Three independent confirmations that the field is agent-authored

• services/aep-api/internal/spec/design_json.go — // Stories is the agent-authored list of PRD stories this component serves. Nothing recomputes it; the fold copies it straight through.
• services/aep-api/internal/spec/build_gate.go — componentStoryClaims reads stories only from components/<id>/design.json, and CellFacts has no story field at all. There is nothing in the cell for the platform to restamp from.
• skills/cell-design/SKILL.md already agrees: "The cell carries structure only. Which PRD stories a component serves is recorded in that component's design.json stories list during enrichment … never in the diagram."

The cell's [stories:] suffix was retired and no skill teaches it any more. This bullet is what survived it.

Change

stories removed from the recomputed-and-overwritten class, with a pointer to the field that owns it. wiring stays — that one genuinely is restamped.

-- **Recomputed and overwritten** on every save: a dependency's `wiring` object,
--  and the component's `stories` array — the platform restamps it from the
--  design.cell citations, so cite stories in the CELL, never here.
++- **Recomputed and overwritten** on every save: a dependency's `wiring` object.
+   … `stories` is NOT in this class — it is yours to author, per the
+   **stories** field above.

One file, prose only, no code or contract change.

Verification

Found while debugging a report of "spec validation failed after the design phase" on a local stack — the failure reproduced on every project. I have not yet driven a full design→build cycle against the corrected skill (that needs a coding-agent run); the case for the change rests on the three code/skill facts above, each of which is checkable without a run. Worth a reviewer confirming that reading before merge.

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a563fc0c-063a-47e3-9fa1-0bfcbe1567c5

📥 Commits

Reviewing files that changed from the base of the PR and between b71d959 and dbe0a0d.

📒 Files selected for processing (1)

• skills/architecture/SKILL.md

Included review availability: Your plan includes up to 1 review per rolling hour; 0 remain after this review.

---

📝 Walkthrough

Summary

• Clarified that component stories are authored in design.json.
• Kept dependency wiring as a platform-recomputed field.
• Updated skills/architecture/SKILL.md only. No code or contract changes.

Walkthrough

The architecture guidance now states that dependency wiring is recomputed and overwritten when saved. The stories array remains authored by the user. The platform no longer generates stories from design.cell citations.

Suggested reviewers: hevayo, xlight05

Merge Risk: ⚪ Minimal · up to dbe0a

This localized documentation correction removes a contradictory instruction about authoring component story coverage; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the contradictory stories guidance, its build-gate impact, and the prose-only fix.
Title check	✅ Passed	The title clearly identifies the architecture skill contradiction involving stories and its build impact.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/architecture-stories-are-authored

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[axewilledge]

Closing — folding this into #470 at the author's request so it can be tried out in one place. The fix is carried there as commit 3c7d959, plus a follow-up (5425195) for the deeper cause found afterwards: the canonical design.json template in the same skill omitted both stories and skillsPinned, which is why a real generated design had neither field.