# Prerequisites are documented

- **Pattern:** `ab-000994` (`developer-documentation.getting-started.prerequisites`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-000994
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-000994)

## Why it matters

Undocumented prerequisites turn a five-minute setup into an hour of debugging. When a project silently requires Node.js 18+ for native fetch, a running Postgres instance, or an active Stripe account, developers on Node 16 or without the external service hit cryptic runtime errors with no path to resolution. iso-25010:2011 analysability treats prerequisite documentation as a core input to understanding a system. The failure mode is invisible: the code looks correct, the install succeeds, and then execution fails for reasons that have nothing to do with the code itself.

## Severity rationale

High because missing prerequisites cause silent environment failures that block setup entirely, and the resulting errors are rarely self-diagnosing — developers waste significant time before discovering the real dependency.

## Remediation

Add a Prerequisites section immediately before Installation. Be version-specific and include external service accounts:

```markdown
## Prerequisites

- Node.js >= 18
- PostgreSQL >= 14 (or a Supabase account — free tier works)
- An OpenAI API key ([get one here](https://platform.openai.com/api-keys))
- ffmpeg installed locally (`brew install ffmpeg` on macOS)
```

Version ranges must be explicit ('Node.js >= 18', not 'Node.js'). Every external service or API key the project requires at runtime must appear here.

## Detection

- **ID:** `prerequisites`
- **Severity:** `high`
- **What to look for:** Check whether the README or docs list required runtime versions (Node.js >= 18, Python >= 3.10, etc.), required system dependencies (e.g., ffmpeg, imagemagick, database servers), and required accounts or API keys for external services (e.g., "You need a Stripe account" or "Requires an OpenAI API key"). Count all instances found and enumerate each.
- **Pass criteria:** Prerequisites are listed before installation instructions. Required runtime versions, system dependencies, and external service accounts are all documented. Version requirements are specific (not just "Node.js" but "Node.js >= 18"). At least 1 implementation must be confirmed.
- **Fail criteria:** No prerequisites section exists, or major requirements are undocumented. The project requires Node.js 18+ but doesn't say so, or it requires a database server but the docs assume one is already running.
- **Skip (N/A) when:** The project has zero dependencies and runs on any standard runtime version.
- **Detail on fail:** Example: `"Project requires Node.js 18+ (uses native fetch) but README does not mention any version requirement"` or `"Project imports from @supabase/supabase-js but docs never mention needing a Supabase account or database"`
- **Remediation:** Add a prerequisites section before installation:

  ```markdown
  ## Prerequisites

  - Node.js >= 18
  - A Supabase account (free tier works)
  - An OpenAI API key ([get one here](https://platform.openai.com/api-keys))
  ```

## External references

- iso-25010 maintainability.analysability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-000994