# Launch-readiness report Human Guide

## What This Is For
Run every Convex audit (authz, reviewer, advisor, insights) into one scored, deduped readiness report with an ordered fix plan — Lighthouse for your backend. It gives the agent a clearer input/output frame for paid media: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the Launch-readiness report agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for launch-readiness report.
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the Launch-readiness report guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- RUN THE PASSES, each emitting findings on the bus:
- convex-authz — the authz scan (identity-from-arg, missing ownership, PII leak, parent-ref-on-write). Always runnable on code.
- convex-reviewer — validators, indexes-not-filter, idiom, error handling. Always runnable on code.
- convex-advisor — live read-limit / OCC evidence (only if a deployment with traffic exists; else record 'skipped: no traffic').
- convex-insights — recent failures from logs (only if a deployment exists).
- Never claim more coverage than was run: the report header lists which passes ran, which were skipped and why. A green score on a code-only run is 'code looks ready', not 'production-verified'.
- Compose, don't re-implement: run the existing audit capabilities and aggregate their bus findings — never re-derive an authz or perf check inline.
- The score counts CONFIRMED findings only, by severity, with the formula printed; plausible findings are candidates that don't move the number.
- Every finding carries its fixCapability; the report ends with an ORDERED fix plan (data-loss/authz first, then scale, then idiom/observability).
- Re-run affected passes after fixes and show the score delta — a readiness number that doesn't move when you fix things is theater.
- Never claim more than was run: header lists ran/skipped passes; a code-only run yields a code-only score, explicitly labeled.
- This is a read + aggregate + dispatch pass; fixes happen in the fixer capabilities, gated by their own consent/deploy-target rules.

## Decision Points And Nuance
The original skill emphasizes: Workflow, Rules.

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- Never claim more coverage than was run: the report header lists which passes ran, which were skipped and why. A green score on a code-only run is 'code looks ready', not 'production-verified'.
- Compose, don't re-implement: run the existing audit capabilities and aggregate their bus findings — never re-derive an authz or perf check inline.
- The score counts CONFIRMED findings only, by severity, with the formula printed; plausible findings are candidates that don't move the number.
- Never claim more than was run: header lists ran/skipped passes; a code-only run yields a code-only score, explicitly labeled.

## Copy-And-Paste Prompt
```text
Use the Launch-readiness report human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the get-convex/agent-skills skill entry for `convex-launch-readiness`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

# Launch-readiness report

Readiness is not one check — it's the union of the checks, deduped, ranked, and scored. This capability is pure composition over the findings bus (specs/finding.schema.json): it runs each audit capability, normalizes their outputs into one report (specs/finding-report.schema.json), computes an auditable score, and — because every finding names a fixCapability — hands the user a prioritized, actionable punch list instead of four separate reports. It fixes nothing itself; it decides WHAT to fix and in what order, then dispatches to the fixers.

## Workflow

1. GUARD + SCOPE: deploy-guard classifies the target (local-anonymous / dev / preview / prod); announce it. Detect what's assessable — is there a convex/ dir, a deployed deployment with traffic, an auth foundation? Skip passes whose preconditions aren't met and SAY which were skipped (a skipped pass is not a pass).
2. RUN THE PASSES, each emitting findings on the bus:
   - convex-authz — the authz scan (identity-from-arg, missing ownership, PII leak, parent-ref-on-write). Always runnable on code.
   - convex-reviewer — validators, indexes-not-filter, idiom, error handling. Always runnable on code.
   - convex-advisor — live read-limit / OCC evidence (only if a deployment with traffic exists; else record 'skipped: no traffic').
   - convex-insights — recent failures from logs (only if a deployment exists).
   Run independent passes concurrently; each returns findings, not fixes.
3. NORMALIZE + DEDUPE: collect all findings into one report. Set each finding's `identity` field to a normalized function/table key (e.g. `messages:list`) that is the SAME whether the pass reported a code-locus or a deployment-locus for that function — so the SAME defect seen from two loci (reviewer flags a missing index at code-locus, advisor flags its read-limit symptom at deployment-locus) collapses to ONE via the bus's (class, identity) dedup and isn't double-counted in the score. Keep the higher-confidence source. Drop nothing silently; a pass that errored/was skipped is a stated coverage gap, not a clean result.
4. SCORE, auditable: start at 100; subtract per CONFIRMED finding by severity (high −15, med −5, low −1), floor at 0; print the exact formula and the per-class breakdown so the number is reproducible, not a vibe. plausible-only findings are listed as candidates but do NOT move the score (evidence-not-vibes). A deployment/traffic-less run reports a code-only score and says so.
5. REPORT: the score, then findings ranked by severity, each with its evidence, its locus, and the fixCapability + a one-line fix note. Group by 'blockers' (high) / 'should-fix' (med) / 'nice-to-have' (low). End with the ordered fix plan: which capability to run next, in what order (authz/data-loss first, then perf/scale, then idiom/observability).
6. DISPATCH on request: for each finding the user accepts, invoke its fixCapability (convex-authz, convex-reviewer's fixers, migrate-rehearse for schema changes, suggest for component swaps). After fixes, RE-RUN the affected passes and show the score delta — the readiness number is only meaningful if it moves when you fix things.
7. Never claim more coverage than was run: the report header lists which passes ran, which were skipped and why. A green score on a code-only run is 'code looks ready', not 'production-verified'.

## Rules

- Compose, don't re-implement: run the existing audit capabilities and aggregate their bus findings — never re-derive an authz or perf check inline.
- The score counts CONFIRMED findings only, by severity, with the formula printed; plausible findings are candidates that don't move the number.
- Normalize each finding's locus to a function/table identity before dedup (map deployment functionId ↔ code file:line) so one defect seen from two loci collapses to one and isn't double-scored; keep the higher-confidence source; drop nothing silently.
- Every finding carries its fixCapability; the report ends with an ORDERED fix plan (data-loss/authz first, then scale, then idiom/observability).
- Re-run affected passes after fixes and show the score delta — a readiness number that doesn't move when you fix things is theater.
- Never claim more than was run: header lists ran/skipped passes; a code-only run yields a code-only score, explicitly labeled.
- This is a read + aggregate + dispatch pass; fixes happen in the fixer capabilities, gated by their own consent/deploy-target rules.