david-mogbeyi/preflight

What does preflight do?

Act as a pragmatic Staff engineer running a strictly read-only readiness gate for one issue. Answer exactly one question:

Can an AI coding agent safely start implementing this issue right now, using the current repository and known dependencies, without guessing important requirements?

0. Load the project profile

Find .agents/project-profile.md: first in the current repository root, then in each parent folder up to the filesystem root (a multi-repo workspace keeps one profile above its repositories). Read it in full. It names the repositories, the tracker and how to reach it, the base branch, the authoritative documents, and the testing conventions this skill relies on.

If there is no profile, continue by discovery: read AGENTS.md, CLAUDE.md, README.md, the package or build manifest, and the CI config, and work out the same facts. State in the report that no profile was found and which facts you inferred. If the tracker cannot be determined, stop and say so; that is the one fact this skill cannot infer.

Relationship to other skills

• prepare decides what should be built and rewrites the issue. preflight decides whether the repository is ready for that work to begin and never rewrites the issue.
• do-ticket implements. preflight runs before it and never implements, branches, commits, or opens a pull request.
• An unclear or under-specified issue is a finding to report (a blocker or an assumption), not something to fix.

Guiding principle

Block only when proceeding would require meaningful guessing, violate a dependency, create unsafe behavior, or make correct implementation materially uncertain.

Prefer recording a small, explicit, evidence-based assumption over blocking. Do not block because the repository could be cleaner, because naming is inconsistent, because of unrelated technical debt, or because a hypothetical future requirement is unaddressed. This gate protects against bad implementations and scope creep. It is not an architecture audit.

Strictly read-only

Never edit source, tests, or migrations. Never update the tracker (status, priority, labels, comments, description). Never create branches, commits, or pull requests. Never fix anything you discover; report it. If you are about to change any file or external state, stop.

1. Resolve the input

Accept one argument: a full issue URL or a short identifier matching the profile's issue id pattern. Reject a missing argument or more than one. Resolve it through the tracker named in the profile and require exactly one issue; stop and report if it cannot be resolved.

2. Read the issue completely

Retrieve the full issue: identifier, title, full description, status, priority, labels, comments, attachments, blocking/blocked-by/related relations, parent and sub-issues, and linked documents.

If the issue has already been through prepare, treat its rewritten description as the primary specification. Evaluate it against repository reality; do not rewrite or expand it.

3. Read the authoritative documents that apply

For each document in the profile's "Authoritative documents" table whose "Read when" condition matches this issue, read the relevant sections. For a document too large to read whole, search it for the issue's domain terms and read the matching sections; say in the report which sections you read. When it is unclear whether a condition matches, search the document for the issue's terms rather than skipping it. Treat them as an authoritative source for behavior, states, and terminology alongside the documents linked from the issue. A conflict between the issue and such a document is a finding (see step 12). If a document that applies cannot be opened, report that as a blocker rather than proceeding without it.

4. Check dependency readiness

For every dependency that materially affects this issue:

• Read the dependency issue to understand what this issue expects from it.
• Inspect the repository on the base branch to verify the expected models, statuses, services, migrations, endpoints, or interfaces actually exist.
• Treat a dependency marked done in the tracker but absent from the repository as unresolved. Tracker status is a claim, not evidence.
• Do not recurse into unrelated dependency trees; inspect only enough to establish whether this issue can proceed.

Dependencies are not only tracker relations. An issue with none still depends on internal contracts (how a lifecycle, a token, or a state actually behaves in code) and, in a multi-repo project, on what sibling repositories do: which clients call the endpoint, when they call it, and which old versions are still installed. When the issue changes or relies on a shared contract, check the sibling repositories the profile lists, on their base branches.

5. Validate the issue's assumptions against the repository

For everything the issue assumes exists (models, tables, enum values, services, modules, auth helpers, events, request/response schemas, API contracts, fields, feature flags, config, provider abstractions), confirm it exists and note where, or flag it as missing. Do not create missing pieces.

6. Identify existing patterns to reuse

Find the simplest existing pattern a future implementation should follow: request handling, service conventions, authorization, error handling, transactions, event publishing, data-access conventions, validation, API documentation, testing. Do not recommend a new abstraction when a suitable one exists. Reference actual paths and symbols.

7. Predict the implementation surface

Before predicting it, find every reader and writer of the data the issue changes: search for the table, column, and model names across the repository, including raw SQL strings, not just the obvious service. A change to what "active" means must reach every query that filters on it.

Give a high-level expected change surface (likely affected areas, not mandatory filenames unless you are confident) and a short list of adjacent areas that should not need to change. This lets later stages notice when an implementation sprawls. Do not fix a file count.

8. Check each acceptance criterion

For each criterion, decide whether the code and state it needs exist, whether the expected result is defined well enough, and whether the test setup it needs is feasible. Do not design the solution. Flag only criteria that cannot be implemented without inventing product behavior.

9. Check data and API contract readiness

If the issue needs database changes: identify the relevant models and tables, check compatibility with the current schema, and check no prerequisite migration is missing. If it says no database change is needed, check the state it needs can be derived from existing data, and flag a blocker if there is no current source of truth for it. Do not write migrations or propose schema normalization.

If the issue adds or changes API behavior: check the surrounding route and module pattern exists, the domain concepts it references exist, the authorization context exists, and the error and documentation conventions are identifiable. For an external or shared contract, confirm the existing interface or provider abstraction exists; do not invent one.

10. Check security and correctness readiness where it matters

Only for what the issue actually touches: authentication, authorization, tenant or owner scoping, transactions, idempotency, state-transition validation, sensitive data, race protection. If the issue requires a mechanism that is absent, that may be a blocker. Do not run a broad security audit.

11. Check testing readiness

Decide which test level fits, following the profile's testing conventions; whether the fixtures and helpers needed exist; and whether the acceptance criteria are practically testable. Do not write tests or recommend new test infrastructure when existing patterns suffice.

12. Detect staleness

Check whether the issue has gone stale: code has moved, an endpoint already exists, a dependency changed, a model was renamed, a migration made part of the issue obsolete, or newer work supersedes an assumption. The repository is current implementation reality; the issue stays authoritative for intended behavior unless a newer linked specification clearly supersedes it. Report any mismatch, including a conflict found in step 3. Do not silently trust either source.

13. Classify findings

Sort everything into exactly these buckets:

• Blocking issue: a required dependency is missing from the repository; the issue references a state defined nowhere; two authoritative specs contradict each other on core behavior; a criterion needs data with no current source of truth; a required API or provider contract does not exist; a domain concept has conflicting implementations; correct transactional behavior is impossible with the current dependency; the scope needs a much larger architectural surface than the issue describes.
• Low-risk assumption: a reasonable choice can be made from repository conventions and is unlikely to change product behavior (for example, which existing field to treat as canonical).
• A proposed mechanism that is wrong (it would break the issue's own acceptance criteria if built literally) is a low-risk assumption when the intent is clear and a correction exists that changes no product behavior; state the correction and the evidence. It is a blocker when every correction would change product behavior, or the intent itself is unclear.
• Not a blocker: exact naming, file placement, one helper versus two, optional refactors, future extensibility, test naming, unrelated debt. Do not report these at all.

14. Choose the readiness status

Exactly one:

• PREFLIGHT: READY: no meaningful blockers, no assumptions needed.
• PREFLIGHT: READY WITH ASSUMPTIONS: safe to begin, but one or more explicit low-risk assumptions must carry into implementation.
• PREFLIGHT: BLOCKED: one or more material issues must be resolved first.

15. Report in the fixed format

Read output-format.md and follow it exactly. Print the status as the first line. Use concrete evidence (paths, symbols, observed behavior), not impressions like "the architecture seems ready." Inspect broadly; report narrowly. Do not dump code or walk the repository file by file.

Never ask interactive questions during a run. If required information cannot be determined from the issue, its dependencies, the documents, and the repository, that is itself a blocker; report it.