Project Doctor.

The Project Doctor audits a project on demand — every phase, plus wishes and amendments — and reports what's missing or thin. Open it from the stethoscope icon on the project's right rail.

If you're trying to ship a project and the team can't agree on whether it's "done," run the Doctor first. It surfaces the blanks before a coding agent or a stakeholder finds them.

Who can use it #

Owners, admins, and editors. Viewers and stakeholders don't see the icon — the findings are actionable for them only inasmuch as the people who fix them have access, so we hide the panel rather than show a read-only view.

Running a check #

Click the icon. The panel slides in with an empty state and a single Run check button. Click it. The check is synchronous and finishes in well under a second on real-world projects; the panel shows a brief "Inspecting spec…" state and then renders findings.

After a successful run you'll see:

• A summary strip with three counters — Critical, Warnings, Info.
• The findings list, grouped by section in spec order (Vision → Features → Brief → Design → Architecture → Quality → Security → Locks → Wishes → Amendments).
• A Re-run check button at the top, plus a "Last run · 3m ago" timestamp.

What the three severities mean #

• Critical — the spec is missing something the rest of the pipeline relies on. Brief without an overview, vision without a value prop. These will silently break downstream phases or BMAD compose. Fix these first.
• Warning — useful content is missing or thin. A feature without acceptance criteria, no critical flows for QA. Spec will compose, but coding agents will have to guess.
• Info — observations, not blockers. "No phases locked yet," "3 stakeholder wishes pending triage." Helpful nudges if a project has been parked for a while.

Findings inside each severity bucket are sorted by spec phase order so you can read top-down.

Deep-linking #

Every finding is a link. Click the row and the Doctor closes; you land on the page that owns the gap, with the right side panel pre-opened where it makes sense:

• Vision · Problem statement → Vision phase page.
• Architecture · Frontend stack not selected → Architecture phase, with Project Settings panel pre-opened (because that's where you pick a frontend).
• N pending wishes → current phase, Wishes panel pre-opened.
• N proposed amendments → current phase, Amendments panel pre-opened.

You're never two screens away from the fix. Click finding → land on the page → make the change → optionally come back and re-run to confirm zero issues.

What the Doctor checks #

Eleven check groups, all pure functions over the project document:

• Vision — problem, value prop, primary users / personas, timeline.
• Features — at least one feature; each feature has a story and acceptance criteria.
• Brief — overview, goals, success criteria.
• Design — at least one screen or component, navigation map, accessibility notes.
• Architecture — frontend (if hasFrontend), backend, database, entities, endpoints.
• Quality — test framework, critical user flows.
• Security — auth model, roles + permissions matrix.
• Phase status — any phase flagged needs-review (usually because an upstream phase changed after lock).
• Locks — info ping if no phase has been locked yet.
• Wishes — info ping for pending stakeholder triage.
• Amendments — warning for proposed amendments (they block downstream regeneration until resolved).

The check matrix is in lib/spec/doctor.ts if you want to extend it for your team's conventions. Each check is a small function that pushes findings into a shared list.

When to run it #

Common moments:

• Before locking the Vision phase — catch missing problem or valueProp while you're still in the conversation.
• Before handing the spec to a coding agent — the BMAD pack composes off real content, not blanks. A clean Doctor run is a strong "ready" signal.
• When inheriting a project — running the Doctor on a project someone else built is the fastest way to see what state it's in.
• After a long pause — projects that sit get stale; the Doctor's "needs-review" pings catch downstream cascades.

What the Doctor doesn't do #

• It doesn't write to the spec. Every action is in your hands.
• It doesn't run automatically. Manual trigger only — we want you to choose the moment, not have a panel pulse at you.
• It doesn't replace human review. Acceptance criteria can be present and still wrong; the Doctor just confirms presence.