docs(spec) scaffold complete spec system + showcase README rewrite#64
Merged
Conversation
Establish the comprehensive spec-doc system that makes the project's "enterprise reference application" goal mechanically checkable, with guardrails and quality gates that span from per-PR audits through launch readiness. Adds: - docs/vision.md — showcase positioning + prospect journeys + what this is NOT + why pinball as the vehicle - docs/guardrails.md — seven main goals; scope discipline (three-bucket triage); decision framework (autonomous-vs-surface table); per-PR / per-phase / pre-public-launch gates; risk register with 10 initial entries; spec maintenance triggers; decision-log spec; build-time and run-time escalation triggers; monthly self-evaluation cadence - docs/build-spec.md — phased plan with Phase 0/1 retrospectives; Phase 2 fully specified (9 scope items, 18 exit criteria, 8 risks); Phases 3-7+ scaffolded; comprehensive deferred-features index - docs/quality-spec.md — every quality gate (current + future) across code, tests, review, docs, ops, accessibility, security, cost; the ratchet rule (never lower a gate); XML doc completeness explicitly out of scope - docs/decision-log.md — scaffolded with format definition and ADR-vs-log threshold - .markdownlint.json — project-wide MD024 siblings_only (allow phase- template repeated subheadings) and MD013 disabled (long-line prose is the existing convention) Updates: - README.md — showcase-first rewrite with architecture diagram, current phase status, doc tree, accurate test/manufacturer counts, two-tier deploy explanation pointing at ADR-0012/0013 (in-flight per Phase 2) - CLAUDE.md — adds Showcase obligations section; tightens locked invariants by pointing at the spec docs; explicitly de-scopes XML doc comments per feedback memory - .claude/skills/local-review/SKILL.md — drops XML doc completeness check from category #7 The four spec docs (vision/guardrails/build-spec/quality-spec) are intended to be load-bearing for the project's lifetime; they canonicalize what was previously scattered across CLAUDE.md and session-spanning memory. Per guardrails.md spec maintenance, these docs update in the same PR as the work they describe — never as follow-up.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Establishes the comprehensive spec-doc system that makes the project's "enterprise reference application" goal mechanically checkable. The four load-bearing docs (vision / guardrails / build-spec / quality-spec) canonicalize what was previously scattered across CLAUDE.md and session-spanning memory, and replace
scraper_plan_v4.md(Phase-1-only) andparallel_execution_plan.md(now historical) as the project's master plan and quality framework.The README is rewritten to lead with the showcase positioning instead of "scraper for sternpinball.com" — manufacturer count corrected (10
ISourceScrapers across 8 manufacturers + OPDB), test count updated (507 vs the stale "7 tests pass"), Aspire foundation surfaced, two-tier deploy explained, doc tree linked at the top.CLAUDE.mdand the/local-reviewskill drop their XML-doc-completeness references per the explicit feedback memory; XML doc comments are out of scope unless a public NuGet package ships..markdownlint.jsonis added at the repo root withMD024: siblings_only(allow phase-template repeated subheadings — every phase legitimately reuses the same### Scope/### Exit criteria/ etc. structure) andMD013: false(long-line prose is the existing convention across all spec docs and ADRs).Test Plan
main.dotnet build PinballWizard.slnx --nologoanddotnet test PinballWizard.slnxare expected to remain green (507 / 507).docs/*.mdreference resolves; ADR pointers (0012, 0013) are clearly marked as in-flight Phase 2 work, not committed in this PR.Out of Scope
docs/build-spec.md(9 scope items, 18 exit criteria, 8 risks) but no Phase 2 implementation PRs land here. ADR-0012 (Cosmos schema-vs-data-plane) is the natural first follow-up.Checklist
README.mdand/ordocs/are updated — yes, this PR is the doc updateproject_pinballwizard.mdupdated earlier this session to reference the spec docs as canonical;project_phased_build_sequence.mdandproject_parallel_execution_plan.mdflagged as historicalTODO/FIXME/ commented-out code committed<NoWarn>without justification — N/A; no codePre-push self-audit (additive PRs)
N/A for this PR — docs-only, no scraper / options class / extension / additive code surface. Per
guardrails.md§ "Per-PR gate" andCLAUDE.md§ "PR self-audit", "Doc-only PRs and pure dependency bumps may skip" the audit. Identity check still verified:git log -1 --format='%an <%ae>'→Jim Keeley <94459922+jkeeley2073@users.noreply.github.com>✅🤖 Generated with Claude Code