Vibe Documentation — Fagan Inspection Report

05_building_block_view.adoc lines 63-65 state: "The external systems are the same set named in [section-context-and-scope]." They are not.

The documentation contract requires "one system boundary in both". The two chapters disagree, and Chapter 5 asserts an equality that is false.

01_introduction_and_goals.adoc lines 87-89: "Chapter 10 elaborates all eight ISO/IEC 25010 characteristics with measurable scenarios."

Chapter 10 (10_quality_requirements.adoc) provides six-part quality scenarios for only five characteristics — Security, Performance Efficiency, Reliability, Compatibility, Maintainability. The other three — Usability, Functional Suitability, Portability — appear only as one-line rows in the quality-tree table (lines 44-54) with no scenario and no measure. Chapter 1’s claim overstates Chapter 10’s content.

08_concepts.adoc Security table (lines 73-77) maps threat T-007 — "A malicious hook command runs as a shell subprocess" — to the mitigation "Tiered tool permissions". But a hook is not a tool: the Glossary (12_glossary.adoc lines 56-58) defines a Hook as a TOML-declared shell command run on a lifecycle event, distinct from a Tool. Tiered tool permissions gate tool calls and do not gate hooks.

Chapter 11 (11_technical_risks.adoc lines 66-70) gives the same threat (via R-006) a different mitigation: hooks are "gated by `enable_experimental_hooks`" plus a 30 s timeout and 3 retries. The two chapters describe different controls for one threat, and the Chapter 8 mapping is incorrect.

10_quality_requirements.adoc lines 66-67: "Every response measure carries a literal figure recovered from code."

The blanket claim contradicts the table it introduces.

05_building_block_view.adoc line 129 names the ACP Bridge interface VibeAcpAgentLoop. 06_runtime_view.adoc line 150 says new_session "creates a fresh AcpSessionLoop`". The two names are used for the ACP session abstraction without stating their relationship, and `AcpSessionLoop carries no file:line evidence of its own.

The spec State Machine diagram (spec/use-cases-vibe.adoc lines 399-411) models four states — Default, Plan, AcceptEdits, AutoApprove. The Glossary lists seven built-in profiles (12_glossary.adoc lines 18-21: adds chat, explore, lean), and the prose immediately below the diagram (lines 413-415) discusses the read-only chat profile, which the diagram does not contain.

Chapter 3 Business Context (03_context_and_scope.adoc lines 26-28) and the spec Actors table (spec/use-cases-vibe.adoc lines 22-23) treat Developer and Scripter / CI as two separate actors. The Chapter 5 Level-1 diagram (05_building_block_view.adoc line 21) merges them into one Person(dev, "Developer / Scripter"). The actor set is not stable across the document.

11_technical_risks.adoc lines 122-126 (TD-004) describes the TUI widget layer as "the least diffable part of a recovery run" — a subjective judgement no reader can test — and quantifies it as "~70 widget modules". The figure is approximate and the only evidence is a directory link (vibe/cli/textual_ui/widgets/); the recovery method itself rates a directory as too coarse to anchor a leaf claim.

11_technical_risks.adoc lines 73-75 (R-008) states "~80 direct dependencies". The cited evidence pyproject.toml:30-141 is a line range, not a count; the figure cannot be checked against it and is hedged with "~".

11_technical_risks.adoc lines 16-17 says priority is "derived from probability × impact", but the derivation rule is never given and is not applied consistently:

The two combinations weigh probability and impact differently. With no stated rule the priority column is not reproducible.

adrs/adr-002-llm-backend-abstraction.adoc lines 45-55: the chosen option, "Backend factory + adapters", scores a total of 0 — identical to the baseline "Single-provider". The matrix therefore does not discriminate in favour of the decision, and the ADR text does not acknowledge that the matrix is non-conclusive.

10_quality_requirements.adoc lines 44-54: the three derived characteristics carry only qualitative notes — e.g. Functional Suitability: "Tool suite + agent loop deliver the stated function"; Performance Efficiency: "Concurrent tools, streaming, bounded I/O". These are claims, not measurable requirements, and unlike the five top-goal characteristics they receive no scenario.

11_technical_risks.adoc lines 68-70 (R-006 mitigation) asserts "Hooks are gated by enable_experimental_hooks`" — a claim about code behaviour. No `file:line evidence is given for this flag, here or anywhere else in the documentation set (it appears in neither Chapter 8, the Glossary Hook entry, nor the system use cases). In a document whose method is evidence-cited code recovery, an uncited behaviour claim is a defect.

08_concepts.adoc cites AGENTS.md:71-79 twice for unrelated topics: the logging configuration ("level and rotation size are env-configurable", Observability, line 137) and the raise … from e exception-chaining discipline ("Exception discipline", Error Handling, line 160). One range cannot back both facts; at least one citation is wrong.

The spec Entity Model PlantUML (spec/use-cases-vibe.adoc lines 344-389) draws the relationship LLMMessage "1" o-- "many" ToolCall and lists tool_calls : ToolCall[] as an attribute, but ToolCall is never declared as a class with attributes, unlike the six entities that are. The Evidence list (lines 391-395) cites no source for ToolCall.

The specification files live in src/docs/spec/. The prose references to them omit the spec/ segment:

None of the three paths resolve to the actual file.

08_concepts.adoc (line 22), 09_architecture_decisions.adoc (line 67), 11_technical_risks.adoc (line 19), spec/prd-vibe.adoc (lines 129) and spec/use-cases-vibe.adoc (line 488) refer the reader to OPEN_QUESTIONS.adoc; arc42/arc42.adoc (line 17), spec/prd-vibe.adoc (line 13) and spec/use-cases-vibe.adoc (line 12) refer to QUESTION_TREE.adoc. Both files exist only at the repository root, outside src/docs/. The documentation contract requires cross-references to resolve inside src/docs/ and explicitly forbids pointing at the Question Tree.

09_architecture_decisions.adoc line 46 and adrs/adr-001-hexagonal-ports.adoc state ADR-001 is "concretised in Chapter 8 (Configuration, Observability)", but neither the Chapter 8 Configuration nor Observability section back-references ADR-001. Likewise adrs/adr-003-middleware-pipeline.adoc claims it "realises the Reliability … mechanisms in Chapter 8", yet no Chapter 8 section back-references ADR-003 for reliability (only the Security table row does). The contract requires Chapter 8 concepts to back-reference the ADR that decided them.

Throughout the specification the CLI command vibe is hyperlinked to the vibe/ source directory and labelled "vibe/", conflating the command with the package directory. Examples: SUC-1 heading "The vibe/ command-line interface" (spec/use-cases-vibe.adoc line 248); UC-2 Trigger "vibe/ -p" (line 112); UC-1 Trigger "Developer runs vibe/" (line 69); Chapter 7 "the single vibe/ … process" (07_deployment_view.adoc line 60).

spec/use-cases-vibe.adoc line 77 (UC-1 Preconditions): "or onbarding (UC-7) runs first" should read "onboarding".

spec/use-cases-vibe.adoc lines 509-515: the Gherkin "Feature: Programmatic price ceiling" is tagged "(UC-2, BR-5)". BR-5 states "Programmatic mode forces the auto-approve agent" (line 476) — it has nothing to do with the --max-price ceiling the scenario exercises. No business rule in the catalogue actually covers the price ceiling, so the traceability tag is misleading.