Startup Audit

Startup Audit

Read an already-built product and give a fast, code-grounded Continue / Pivot / Kill triage call. Ingest the codebase (and optionally a live URL), infer the business model into a Lean Canvas, diff coded reality against the claimed story, and ship a self-contained interactive HTML dossier that opens with the verdict.

This skill is a fast triage, not a deep adversarial verdict. Its Stage 2 is a single-pass per-lens findings sweep — no rebuttal round — so the verdict is an honest first read, not a grilled one. For a consequential call (especially Kill or Pivot), the dossier points to startup-grill for the adversarial confirmation. Every claim is tiered by confidence and pinned to a provenance pointer; overclaiming is the cardinal sin. The verdict is opinion, not advice — the disclaimer ships with every run.

A pure-diligence dossier (evidence only, no verdict) is available on request — see Phase 0 mode detection.

---

STOP — When NOT to use this skill

Hand off — do not run the audit — if any of these apply:

• The product doesn't exist yet (idea / pre-build) → use startup-launch-kit

or validation-canvas. There is no codebase to read; this skill would have nothing to infer from.

• The product exists, but the user wants the full 5-artifact kit (brand →

canvas → RAT → deck → grill), not a fast verdict → use startup-launch-kit. This skill produces only the Continue/Pivot/Kill triage; the kit is the full-pipeline path (and it reuses this skill's mode=diligence as its code-reader — see Cross-Skill Integration). The split is by output: want the verdict → here; want the kit → there.

• The user wants a DEEP adversarial verdict on belief artifacts (a Lean Canvas

or pitch deck), or wants to confirm a consequential Kill/Pivot this skill flagged → use startup-grill. This skill gives the fast code-grounded triage; grill gives the heavier 3-round adversarial verdict on text artifacts. They are siblings split by input (built code/URL vs belief artifacts) and rigor (triage vs adversarial).

• The user wants deep UI/UX review of an AI feature → use ai-ux-review

(and ai-eval-review for the eval layer). This skill delegates the UI/UX layer to those skills rather than rebuilding it.

• The user wants to audit a SKILL.md's rule adherence → use skill-evaluator.

Different "audit" — that one reads skill text, this one reads a product.

Bright-line rule: if there is no built artifact to read (no repo, no live URL), this is not the skill — pre-build work routes to startup-launch-kit. If the user wants the deep adversarial verdict on a canvas/deck, that's startup-grill.

Redirect discipline. When the STOP gate fires and you route to startup-grill or team-composer, describe the kind of lens needed — don't coin role tags. The canonical persona catalog is skills/team-composer/references/role-personas.md; defer naming specific roles to those skills.

---

Skill Boundaries

| Request | Skill | |---|---| | "Grill my startup from the codebase / repo / URL" | startup-audit (this skill) | | "Should I continue, pivot, or kill — from the code?" | startup-audit | | "Score my built product / does my code match my pitch?" | startup-audit | | "Grill my pitch deck / Lean Canvas (deep adversarial)" | startup-grill | | "Confirm the Kill/Pivot this audit flagged" | startup-grill | | "Build the full kit from my repo (not just a verdict)" | startup-launch-kit (reuses this skill as its code-reader) | | "Validate my idea / build my lean canvas (pre-build)" | validation-canvas / startup-launch-kit | | "Review my AI feature's UX" | ai-ux-review | | "Audit my eval setup" | ai-eval-review | | "Audit whether my SKILL.md rules land" | skill-evaluator |

The split with startup-grill is input + rigor, not evidence-vs-verdict: this skill reads a built artifact and gives a fast triage verdict; grill reads belief artifacts and gives a deep adversarial verdict. When this skill returns a Kill or Pivot, it recommends grill for the heavier confirmation — that's a handoff, not a boundary the user has to manage.

---

What this skill produces

Every run produces files inside the resolved audit root (see Phase 0 for path resolution; default docs/audit/ for solo runs, docs/startup-kit/audit/ when invoked under the kit root):

1. startup-audit.html — the single self-contained interactive dossier. In

default (verdict) mode it opens with the Continue / Pivot / Kill verdict

• Red/Amber/Green band + the disclaimer, then the evidence. In **diligence-only

mode** the verdict section is omitted (evidence only). Format + template: references/dossier-html-template.md.

1. startup-audit.md — canonical, editable Markdown mirror of the dossier.
2. inferred-canvas.md — the inferred Lean Canvas using validation-canvas's

exact headings, every field carrying a provenance pointer + confidence tier.

The handoff bridge (read carefully — this is where the chain connects). Downstream skills do not read inferred-canvas.md: startup-grill and pitch-deck grep /validation-canvas.md, and riskiest-assumption-test reads its own assumption-test-plan.md. So inferred-canvas.md is this skill's evidence artifact, not an auto-consumed pipeline input. The bridge is the offer-to-seed step (Phase 2): if no founder validation-canvas.md exists, this skill offers to seed one — and that seeded file is what grill consumes when the user takes a Kill/Pivot for confirmation. For riskiest-assumption-test, the handoff is a pointer: the dossier recommends running RAT on the unknown blocks. State this honestly — do not imply an automatic feed that isn't wired.

Existing files from prior sessions are appended-to / re-rendered, never silently overwritten. Never overwrite a founder-authored validation-canvas.md — see Phase 2.

---

Phase 0: Path resolution + mode + dependency pre-flight

Resolve the audit root once, in this precedence order:

1. Explicit output_dir arg → use as-is.
2. STARTUP_KIT_DOCS_ROOT env var set → ${STARTUP_KIT_DOCS_ROOT}/audit/.
3. docs/startup-kit/ exists → docs/startup-kit/audit/ (surface the

smart-default notice: "Writing to docs/startup-kit/audit/. Set STARTUP_KIT_DOCS_ROOT=./docs to write standalone instead.").

1. Solo fallback → docs/audit/.

Sibling reads (/, /) resolve as siblings of the audit root, matching startup-grill's chain.

Mode detection. Default mode emits the verdict. Switch to diligence-only mode (evidence dossier, no verdict / no score / no disclaimer-as-opinion) when the user asks for it — phrases like "diligence only", "evidence only", "no verdict", "just the dossier / no opinion", or an explicit mode=diligence arg. Record which mode ran; the dossier states it.

Dependency pre-flight (fail loud). Before doing any work, check that the required sibling skills are present (see Dependencies). If a required reference is missing, refuse with a clear message — do not silently degrade:

> "startup-audit requires team-composer, validation-canvas, and > riskiest-assumption-test to be installed (it reads their reference files and > writes artifacts they consume). One or more is missing — install the full > agent-skills plugin, not just this skill."

Capability gate (degrade with notice). Detect optional runtime capabilities and pick the lane; record which lane ran so the dossier can state it:

• SocratiCode MCP present (mcp__socraticode__codebase_*) → use it for the

semantic map. Absent → glob/grep fallback over high-signal files.

• WebFetch / Playwright present AND user supplied a URL AND URL fetch is

explicitly opted-in → fetch the live surface. Absent / not opted-in → codebase-only; note the URL was skipped. If a fetch is attempted but fails (timeout, auth wall, error) → fall back to codebase-only, record the failure in the lane note, and continue — a failed URL fetch never blocks the audit.

---

Phase 1: Signal extraction (Stage 1a)

Goal: sweep the codebase for deterministic business signal. This is a structured extraction, not a judgment call — precision lives here.

Apply references/signal-extraction.md end-to-end. Detect the ecosystem (JS/TS, Python, or generic fallback) and run the matching extractors over the universal source taxonomy:

dependency manifests · data model / schema · routes / pages · auth & tenancy · .env(.example) · money code · README / docs claims (+ roadmap markers) · commit recency / contributor count.

Secret-redaction rule (hard). Extract key names / presence only — never values. A STRIPE_SECRET_KEY entry in .env.example is signal that Stripe is wired; its value (if ever present) must never be read into any artifact. If a real secret is encountered, record only "" and move on.

Output of this phase is a structured signal set (internal), each signal tagged with its source file/path — that tag becomes the provenance pointer in Phase 2.

---

Phase 2: Inference (Stage 1b) → inferred canvas + build-vs-claim diff

Goal: turn signals into an inferred business model, tiered by confidence, and surface the gap against the claimed story.

Apply references/inference-mapping.md:

1. Infer into the nine Lean Canvas blocks using validation-canvas's exact

headings: ### Problem, ### Customer Segments, ### Unique Value Proposition, ### Solution, ### Channels, ### Revenue Streams, ### Cost Structure, ### Key Metrics, ### Unfair Advantage. (These headings are grepped by startup-grill and riskiest-assumption-test — match byte-for-byte.)

1. Derive the confidence tier from provenance — do not judge it:

• observed — a deterministic signal is directly present (e.g. an

invoice.paid webhook handler + a populated plan table).

• inferred — reasoned from a pattern (e.g. a Stripe dep + a Subscription

entity → probably recurring SaaS).

• unknown — no signal. The block renders empty.
• Hard gate: provenance == null → the field cannot render as a claim.

No provenance pointer, no claim. Unknowns stay unknown; they are not filled by reasoning about the market.

1. Build-vs-claim diff (the headline evidence). Contrast the inferred (coded)

model against the claimed story (README / marketing copy / URL). Run it bidirectionally: claimed-but-not-built AND built-but-not-claimed. Parse README roadmap markers ("Future", "Coming soon", "Roadmap") — a feature the tagline sells but the roadmap marks "Future" is a diff finding.

Write inferred-canvas.md to the audit root. The blocks code evidences poorly — typically Problem, Unique Value Proposition, Unfair Advantage — render as unknown and become the riskiest-assumption-test handoff (these are exactly the beliefs a built artifact can't prove).

Thin / greenfield repos are a valid result, not a failure. A sparse repo (prototype, few deps, no schema) legitimately yields a mostly-unknown canvas. Still run the audit — report the unknowns honestly, downgrade the verdict's confidence accordingly (see Phase 3), and route the unknowns to riskiest-assumption-test. Do NOT pad the canvas with market reasoning to make it look complete; that trips the provenance gate. Yield scales with repo maturity.

Never overwrite a founder-authored validation-canvas.md. Write to the separate inferred-canvas.md. If no validation-canvas.md exists at the canvas root, offer to seed one from the inferred canvas (the founder can then correct the machine's inference) — but only on explicit confirmation.

Orchestrated carve-out (no double-prompt): when invoked with mode=diligence by startup-launch-kit (existing-project mode), the founder's Phase 0.3 opt-in ("read the code and pre-fill the canvas") is the seed confirmation — write the seed directly, do not re-prompt. Standalone invocation still requires the explicit confirmation above.

Seed-header contract (load-bearing — do not drop). The seeded validation-canvas.md MUST retain the machine-inferred provenance header from inferred-canvas.md verbatim (the full blockquote in references/inference-mapping.md), plus each block's _(TIER — provenance)_ tag.

The header opens with the detection marker — the HTML comment ` — which validation-canvas keys on to run its tiered confirm (observed glance / inferred verify / unknown interview) instead of treating the seed as founder truth. This marker is the single source of truth (defined in references/inference-mapping.md): single-line, invisible when rendered, and absent from any founder-authored canvas. validation-canvas and startup-launch-kit/references/state-detection.md detect the seed by matching this exact comment. If you ever change the marker, update both readers in lockstep — a seed whose marker no longer matches reads as a founder-authored canvas downstream and silently launders machine guesses into belief (the exact failure the provenance gate prevents). This matters most when startup-launch-kit` drives the seed in existing-project mode.

---

Phase 3: Audit panel + verdict synthesis (Stage 2)

Goal: apply domain-aware lenses to the inferred canvas + diff, then synthesize a fast triage verdict. This is a single-pass per-lens findings pass, NOT a multi-round debate. The adversarial opening/rebuttal/synthesis panel is startup-grill's job — do not rebuild it here. The verdict here is an honest first read derived from that single pass; consequential calls route to grill for confirmation.

Apply references/audit-panel-resolution.md, then references/verdict-and-scoring.md:

1. Pre-fill team-composer Phase 1 signals from the inference (not from a

brief): tenancy model → audience; compliance configs / regulated entities → is_regulated; ML/LLM deps → is_data_intensive + AI-feature flag; i18n / locale dirs → is_international; voting / nudge / gamification code → involves_behavior_design; commit history / maturity → stage.

1. Resolve the lens panel using the selection algorithm in

audit-panel-resolution.md, which reads personas from skills/team-composer/references/role-personas.md (capability-gated; generic lens fallback if absent). Do not invoke team-composer as a sub-skill — read its catalog, mirror startup-grill's read-then-select pattern.

1. Each composed lens emits exactly one findings block against the inferred

canvas + diff — focused, evidence-anchored, no debate. Every finding cites the canvas field / diff row / signal it rests on, and is tagged with a finding-id (F1, F2, …) and a severity×fixability per verdict-and-scoring.md.

1. AI features detected → add the AI-safety lens AND route to the conditional

skills ai-ux-review (human-AI design + integrity surface) and ai-eval-review (eval rigor). If they run, embed/link their docs/ai-ux/*.html outputs into the dossier rather than re-assessing AI quality here.

1. Options the evidence suggests. Generate grounded options (including pivot

directions). Hard gate: every option must cite the finding that motivates it — no citation, the option is suppressed. When the verdict is Pivot, these options ARE the code-grounded pivot directions.

1. Verdict synthesis (default mode only; skipped in diligence-only mode).

Per references/verdict-and-scoring.md, derive from the tagged findings:

• a headline verdict — Continue / Continue-with-conditions / Pivot / Kill

(the headline carries the recommendation; never let the band stand in for it);

• a Red / Amber / Green heat band (coarse, layered under the headline);
• an **evidence-confide

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sorawit-w
• Source: sorawit-w/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.