Implementation preflight skill and unknowns slash command for AI coding agents

openai.yaml

interface:
  display_name: "Implementation Preflight"
  short_description: "Find unknowns before implementation"
  default_prompt: "Use $implementation-preflight to prepare an implementation plan before starting code changes."

SKILL.md

name	implementation-preflight
description	Prepare higher quality implementations by finding blind spots, unknowns, decision points, prototypes, references, validation risks, and reviewer context before coding. Use before starting a new feature, prototype, game system, tool, design pass, refactor, or any implementation where the prompt may be incomplete, ambiguous, unfamiliar, or likely to uncover hidden constraints.

Implementation Preflight

Purpose

Use this before implementation starts. Convert a rough request into a stronger plan by mapping the gap between the prompt and the real work: codebase constraints, product intent, user taste, domain knowledge, references, risks, and validation.

The agent should be proactive. The user may know what they want only after seeing options, or may omit obvious preferences they would recognize later.

Core Model

Classify context into four buckets:

1. Known knowns: explicit requirements, files, constraints, acceptance criteria.
2. Known unknowns: open questions the user or agent already sees.
3. Unknown knowns: taste, expectations, conventions, and obvious local context the user may not write down.
4. Unknown unknowns: risks, alternatives, missing domain knowledge, hidden implementation constraints, or better approaches the user has not considered.

Aim to shrink the last two buckets before code changes become expensive.

Workflow

1. Restate the job Summarize the intended outcome in a few lines. Include the likely user value, affected surface area, and what would count as done.

2. Run a blind spot pass Search local context first. Inspect repo instructions, adjacent files, existing patterns, tests, docs, design notes, and prior prototypes. If current facts matter, verify them with live sources. List the most important unknown unknowns and why each could change the plan.

3. Find decision points Identify choices where the answer would change architecture, data model, UX flow, asset pipeline, testing approach, or project scope. Put these before mechanical implementation details.

4. Offer prototypes when taste is involved If the task depends on visual design, interaction feel, game mechanics, copy tone, or unclear product taste, propose cheap prototypes before wiring deep systems. Prefer small HTML, script, mock data, paper rules, or isolated module experiments.

5. Ask only high leverage questions Ask questions one at a time only when the answer materially changes implementation. If a conservative assumption is safe, state it and continue.

6. Use references aggressively Look for reference code, prior docs, designs, libraries, screenshots, games, demos, or specs that express the target better than prose. Prefer source code or runnable examples over screenshots when available.

7. Write the implementation plan Lead with decisions most likely to change: data model, type interfaces, UX flow, rule semantics, security boundaries, migration path, and validation strategy. Put routine refactors and file moves later.

8. Plan implementation notes For nontrivial work, create or update a temporary implementation notes file only when useful. Track deviations from the plan, edge cases found, assumptions made, and follow up questions. Remove or fold it into durable docs before finishing unless the repo wants to keep it.

9. Plan reviewer context Decide what final artifact will help review: concise explainer, demo link, screenshots, before and after notes, risks addressed, test evidence, or a small quiz for the user when understanding matters.

Output Template

Use this structure unless the user asks for a different format:

**目標**
一句至三句講清楚要交付乜，同點先算完成。

**已知**
1. 明確需求
2. 現有 repo 或產品限制
3. 可重用參考

**盲點**
1. 可能影響方案嘅未知
2. 點樣快速驗證
3. 如果唔驗證，保守假設係乜

**關鍵決策**
1. 決策
   影響:
   建議:

**需要問你**
只列真正會改變方案嘅問題。可以安全假設就唔問。

**Implementation Plan**
1. 探索或 prototype
2. 核心實作
3. 測試同驗證
4. Review artifact

**開工準則**
清楚列出可以立即開始，或者等待邊一個答案。

Operating Rules

1. Keep the preflight concise enough to act on. Prefer sharp numbered points over long essays.
2. Do not let the first prompt overconstrain the solution. Suggest better approaches when context supports them.
3. Do not ask broad questionnaires. Ask fewer, higher leverage questions.
4. If the work is small and low risk, run a mini preflight mentally and proceed.
5. If the work touches security, user data, payments, auth, deployment, or destructive operations, make risks and assumptions explicit before implementation.
6. If the plan changes during implementation, record the reason and choose the most conservative path that preserves user intent.

unknowns.md

Use $implementation-preflight before starting implementation.

Take the user's current request as the project brief. Produce a concise Chinese friendly preflight that:

1. Summarizes the goal and done criteria.
2. Maps knowns, known unknowns, unknown knowns, and likely unknown unknowns.
3. Searches relevant local repo context before asking questions.
4. Lists only decisions that could change architecture, UX, rules, data model, testing, security, or scope.
5. Suggests cheap prototypes or references when taste, game feel, visual design, or domain judgment matters.
6. Asks only high leverage questions. If a safe conservative assumption exists, state it and continue.
7. Ends with an implementation plan and clear start condition.

Keep the output concise, structured, and bold the important information.