Infrastructurepattern

State-machine capability check (7-state)

"Why is the integration broken?" eats 20-minute Slack threads. Seven precise states, each with the exact fix and time cost printed.

TierBMedium — Solid coverage with concrete examples

EffortM · Weeks

Forengineer · ops lead · any tool that integrates with a shared resource

What

Before offering an auto-write to a shared Google Sheet (or Notion DB, or Linear project, or any team-owned external resource), the tool runs a capability check that returns one of seven precise states, each with the exact fix and a realistic time estimate:

State	Meaning	Fix (with time)
`ready`	Both targets auto-writable	Proceed
`partial`	One target works, other doesn't	Auto-write the good one, manual paste for the other
`schema_mismatch`	Required headers missing	Set `*_TAB` env vars (~30s)
`needs_share`	Creds exist but resource 403/404s	Share resource with printed service-account email (~30s)
`no_credentials`	No service-account JSON	Run `setup_google_sheets.sh` (~5–15min)
`no_id`	`TEAM_SHEET_ID` env var unset	Set it in `.env`
`lib_missing`	Required Python library missing	`pip install <name>`

The user picks based on time cost; nothing is forced.

Why it matters

"Why is the integration broken" is the #1 support burden for any tool that touches a shared external resource. Every failure mode having a printed fix with a realistic time cost converts a 20-minute Slack thread into a 30-second self-service. A founder-discovery CLI uses this pattern; users go from "I'm stuck" to "I picked manual paste" in seconds.

End-to-end

Enumerate every failure mode in the integration. Group into 5–9 states.
For each state, document: the exact symptom, the exact fix command, a realistic time estimate.
Implement tool check that runs probes in order (cheapest first: env vars → library import → API auth → resource read → schema match).
Return early on the first failing state; print the state name, fix, time.
Support --json output for scripting.
In SKILL.md, document the state table so the agent surfaces the right choice without re-discovering it.

Gotchas

Don't gate the entire tool on ready. Many states have valid fallback modes (manual paste, partial auto-write); surface them as menu options, don't force the auto path.

Tools

Whatever the integration uses (Google API libs, Notion SDK, etc.)
A YAML / JSON definition of the schema you require

← All casesB-076