====== Developer Prompt Pipeline ====== A structured 5-step prompting workflow for software developers using AI assistants (Claude, GPT-4, etc.) to go from raw feature request to verified implementation. **Core principle:** Replace subjective model-judged gates with concrete artifacts and real tool output. Every step produces a file. Every file is checkable. ---- ===== Overview ===== ^ Step ^ You do ^ Model does ^ Output file ^ | 1 | Write the request | — | ''raw_request.md'' | | 2 | Provide source files | Technical planning | ''plan.md'' | | 3 | Triage blockers | Structured audit | ''audit.md'' | | 4 | Review task list | Task decomposition | ''tasks/task-NN.md'' | | 5 | Run verifier, paste output | Implement one task | Modified source files | > **Key discipline:** What //you// do between steps matters as much as the prompts themselves. Do not hand triage or task-review decisions to the model. ---- ===== Step 1 — Write the raw request ===== You write this file yourself. Do not ask the model to produce it. This is your contract with yourself and the model for all subsequent steps. ==== File: raw_request.md ==== ## Feature / Bug / Task [One sentence summary] ## Context - What part of the codebase does this touch? - Why is this needed? (user problem or business reason) - Any related tickets, PRs, or prior decisions? ## Requirements - [Requirement 1 — use "must", "should", "must not"] - [Requirement 2] - ... ## Out of scope - [What explicitly NOT to do] ## Constraints - Stack: [e.g. Node 20, React 18, Postgres 15] - Conventions: [e.g. use repository pattern, no raw SQL, tests with Vitest] - Must not break: [e.g. existing auth flow, public API contracts] - Prefer: [e.g. small focused functions, no new dependencies without justification] ## Success criteria - [ ] [Observable, testable outcome 1] - [ ] [Observable, testable outcome 2] ==== Tips ==== * The **Constraints** section is the most important part. The more specific it is, the fewer loops you hit in step 3. * Use "must", "should", "must not" language in Requirements — it forces you to think about priority. * Success criteria should be observable and testable by a human or a test runner, not just "feature works". ---- ===== Step 2 — Create the plan file ===== ==== Prompt ==== You are a senior engineer doing technical planning. Read the following: - `raw_request.md` — the feature/bug request - The relevant source files listed below Source files: [list file paths] Produce a `plan.md` file with these sections: ## Summary One paragraph: what are we building and why. ## Current state How the relevant code works today. Be specific — reference actual files, functions, and data flows. ## Proposed approach Step-by-step technical approach. For each step explain the "why", not just the "what". ## Files to change | File | Change type | Reason | |------|-------------|--------| ## Files to create | File | Purpose | ## Risks and unknowns - [anything that could go wrong or needs a decision before implementing] ## Decisions made - [any design decisions made here and the reasoning] Be concise. Avoid generic advice. Reference specific files and function names from the actual codebase. ==== What to check in the output ==== * Does "Current state" reference actual function names from your code, not generic descriptions? * Does "Proposed approach" explain //why// each step is taken? * Is the "Decisions made" section populated? If empty, the model skipped reasoning — prompt again with: //"For each decision in the approach, explain what alternatives were considered and why you chose this one."// ==== Tips ==== * Always feed this prompt the //minimal// set of source files relevant to the task. Feeding the entire codebase produces vague plans. * The **Decisions made** section is critical — it carries reasoning forward into steps 4 and 5, preventing the model from re-inventing or contradicting decisions mid-implementation. ---- ===== Step 3 — Audit the plan ===== This replaces the open-ended "is it best practice?" gate with a structured, triaged list of concerns. ==== Prompt ==== You are a senior engineer doing a pre-implementation code review. Read: - `raw_request.md` - `plan.md` - The relevant source files listed below Source files: [list file paths] Produce an `audit.md` file. For each concern use this format: --- **[BLOCKER | WARNING | NITPICK]** — [short title] - File/area: [where] - Issue: [what is wrong or risky] - Suggestion: [concrete fix] --- Check for: - Does the plan contradict existing patterns in the codebase? - Are there missing edge cases or error paths? - Will this break any existing behavior or API contracts? - Are there security, performance, or scalability concerns? - Does anything in the plan conflict with the constraints in raw_request.md? - Are there simpler alternatives the plan overlooks? End with a verdict: ## Verdict READY | NEEDS CHANGES If NEEDS CHANGES, list only the BLOCKERs that must be resolved before proceeding. Do NOT suggest changes for WARNINGs or NITPICKs — those can be addressed later. ==== Severity definitions ==== ^ Severity ^ Meaning ^ Action ^ | BLOCKER | Will cause incorrect behavior, data loss, security issue, or breaks the build | Fix before step 4 | | WARNING | Technical debt, suboptimal approach, or risk under specific conditions | Log in a tech-debt note; revisit later | | NITPICK | Style, naming, minor improvements | Ignore or batch into a cleanup task | ==== Tips ==== * **You — not the model — decide what to fix.** Read the audit, triage BLOCKERs yourself, update ''plan.md'', then re-run step 3 only for the changed sections. * This kills the infinite loop. The old "if no, return to step 3" pattern loops forever because the model has no stable definition of "ready". The BLOCKER/READY gate gives it one. * If the audit produces only WARNINGs and NITPICKs, the verdict should be READY. Proceed. ---- ===== Step 4 — Split into tasks ===== ==== Prompt ==== You are a senior engineer breaking a plan into implementation tasks. Read: - `raw_request.md` - `plan.md` - `audit.md` - The relevant source files listed below Source files: [list file paths] Create one file per task in the `tasks/` folder named `task-01.md`, `task-02.md`, etc. Each task file must follow this exact structure: ## Goal One sentence. What does completing this task accomplish? ## Context Why this task exists and how it fits into the overall plan. ## Files to touch - `path/to/file.ts` — what to do ## Implementation steps Numbered, specific steps. Reference real function names, types, and patterns from the codebase. ## Acceptance criteria - [ ] [Concrete, verifiable outcome — prefer test commands or observable behavior] - [ ] [e.g. `npm test src/auth` passes] - [ ] [e.g. POST /api/login returns 401 with invalid credentials] ## Dependencies - Depends on: [task-XX or "none"] - Must complete before: [task-XX or "none"] Rules for task splitting: - Each task must be independently verifiable - No task should touch more than 3–4 files - Order tasks so each one builds on a stable foundation - Prefer: data layer → business logic → API → UI ==== Task review checklist ==== Before running step 5, review the generated tasks yourself: * [ ] Each task has at least one acceptance criterion that can be verified by a test command or observable behavior * [ ] No task touches more than 3–4 files * [ ] Tasks are ordered so each one has a stable foundation (no task depends on something not yet implemented) * [ ] Trivially small tasks (1–2 line changes) are merged into adjacent tasks * [ ] Tasks that touch too many files are split further ==== Tips ==== * **You are the tech lead here.** The model's task split is a first draft, not a final plan. * Prefer the ordering: data/schema layer → business logic → API/service layer → UI/presentation. * Acceptance criteria that say "code looks correct" are not criteria. Require a test command, a curl output, a log line, or a UI behavior. ---- ===== Step 5 — Implement and verify ===== Run this prompt once per task file. Do not batch multiple tasks into one prompt. ==== Prompt ==== You are a senior engineer implementing a single task. Read: - `tasks/task-01.md` — the task to implement (change number each time) - `plan.md` — for overall context and decisions already made - The source files listed in the task Implement exactly what the task describes. Do not implement anything outside this task's scope. Rules: - Follow existing code patterns in the files you touch - Do not introduce new dependencies without flagging it - Do not refactor code outside the task scope - Leave a short inline comment when making a non-obvious choice After implementing, self-check against the acceptance criteria: ## Verification - [ ] [paste each criterion from the task] For each criterion: state whether it passes and how you verified it. If any criterion cannot be verified by you (e.g. requires running tests), output the exact command to run: ``` [test command] ``` Do not mark the task complete until all blockers are resolved. ==== Verification loop ==== For criteria that need real test output, run the command yourself and paste the result back with this follow-up prompt: Test output: [paste output here] Are all acceptance criteria in task-01.md met? If not, what needs to change? This gives the model real evidence to verify against instead of self-assessing. ==== Tips ==== * Always include ''plan.md'' in the context, not just the task file. It prevents the model from drifting or contradicting earlier decisions. * "Do not implement anything outside this task's scope" is important — without it, the model will eagerly refactor surrounding code or pre-implement the next task. * One task per prompt. Batching tasks in one prompt leads to entangled changes that are hard to review and harder to roll back. ---- ===== File structure reference ===== project/ ├── raw_request.md ← Step 1: you write this ├── plan.md ← Step 2: model output, you review ├── audit.md ← Step 3: model output, you triage ├── tasks/ │ ├── task-01.md ← Step 4: model output, you review │ ├── task-02.md │ └── task-03.md └── [your source files] ← Step 5: model modifies these ---- ===== Common failure modes ===== ^ Symptom ^ Cause ^ Fix ^ | Step 3 loops forever | No concrete definition of "ready" | Use the BLOCKER/READY gate; you decide when to proceed | | Step 5 output is vague or generic | Model lost context from earlier steps | Always include ''plan.md'' in step 5 context | | Tasks are too coarse to verify | Acceptance criteria are missing or subjective | Require test commands or observable behavior in every task | | Model refactors unrelated code | No scope constraint in step 5 prompt | Add "do not touch code outside this task's scope" explicitly | | Model marks task complete without real evidence | Self-verification loop | Run the test command yourself and paste output back | | Plan contradicts codebase patterns | Model hallucinated conventions | Feed the actual relevant source files, not just descriptions | ---- ===== Quick reference — prompt inputs per step ===== ^ Step ^ Inputs to provide ^ | 1 | Your own knowledge | | 2 | ''raw_request.md'' + relevant source files | | 3 | ''raw_request.md'' + ''plan.md'' + relevant source files | | 4 | ''raw_request.md'' + ''plan.md'' + ''audit.md'' + relevant source files | | 5 | ''tasks/task-NN.md'' + ''plan.md'' + source files listed in the task |