I built a doctor for Kiro specs, with Kiro's own spec workflow

Mandala — Sat, 14 Nov 2026 13:55:57 +0000

My Kiro specs had a problem I kept tripping over: they looked finished and were not. A requirement would say the system "may" do something. Acceptance criteria read like wishes. Tasks got checked off while the code they described never appeared. The spec was the one artifact nobody audited, so I built the auditor. Spec Doctor is my entry for the Kiroween Hackathon 2026.

Spec Doctor takes the three files of a Kiro spec — requirements.md, design.md, tasks.md — and returns a health score from 0 to 100 with findings that name the file, the line, and the exact quote. The checks are deterministic and run entirely in the browser: vague language, criteria without GIVEN/WHEN/THEN structure or EARS format, untestable wording, requirements no task covers, tasks with no requirement reference, duplicate requirements, oversized tasks, and design sections missing error handling, a data model, or API contracts. The score is reproducible by hand because the report shows every deduction. A bad spec I wrote as a fixture scores 28 with 37 findings. A good one scores 100 with none.

The second half is drift. Upload a repository folder or ZIP and Spec Doctor traces every requirement ID into the code. It reports three kinds of signals: spec items with no implementation, code referencing IDs the spec never mentions, and code files with no ID references at all. I call them signals on purpose. Text matching is not proof, and each one needs a human to decide. Drift never touches the health score.

An optional LLM review adds a second opinion for contradictions and ambiguity. You bring your own OpenAI-compatible key, and it stays in memory only — the app uses no web storage at all. Suggestions land in a separate labeled block and never affect the score.

I built it with Kiro's spec-driven workflow through the Kiro CLI. The spec came first: requirements, design, and tasks generated headless, then reviewed and amended by hand. Two of my amendments mattered. The duplicate threshold became an exact number (Jaccard 0.90 over normalized tokens) instead of "similar". The scoring rule became diminishing deductions without caps, so a spec with twenty critical findings still scores 52 instead of bottoming out at zero. Each implementation task then ran in its own headless CLI session with filesystem tools only and no shell access. I ran every build, test suite, and browser smoke test myself and sent failures back as exact fix instructions.

The smoke tests earned their keep twice. A drift handler shipped scanning an empty file list because the upload handlers discarded the extracted files; unit tests passed and only the browser run caught it. A review button could never enable because its inputs listened for the wrong event and nothing refreshed its state. Both defects were invisible to the 281 unit tests and obvious the moment a real browser drove the real UI. My rule since: the suite proves the logic, the browser proves the wiring.

The dogfood result is the part I like most. Spec Doctor audits its own spec: 82 out of 100 with 9 findings. Six of the nine are self-referential — the spec lists the vague terms the checker flags, so the checker flags the list. The remaining three are loose wordings I chose to keep. I did not edit the spec to reach 100. A tool that grades its own homework to a perfect score is not a tool I would trust.

Spec Doctor is free, client-side, and open source. Demo: https://luecria.github.io/spec-doctor/. Repository: https://github.com/Luecria/spec-doctor. It was built for the Kiroween Hackathon 2026 in the Frankenstein category: a parser, a rule engine, an LLM review, and a report generator stitched into one tool.

DEV Community: Mandala

I built a doctor for Kiro specs, with Kiro's own spec workflow