lidge-jun/prompt-engineering

Prompt & Context Engineering

Analyze a draft prompt, identify gaps, map it to available agent components, and output an optimized prompt the user can paste and run.

2026 note: The field has evolved from "prompt engineering" to "context engineering" — managing the full context window (system prompts, retrieved data, tool schemas, conversation history) rather than just optimizing the wording of a single prompt.

When to Use

• User asks to optimize, improve, or rewrite a prompt
• User asks "what's the best way to ask the agent to..."
• User pastes a draft prompt and asks for feedback

When to Skip

• User wants the task executed directly ("just do it")
• User asks to optimize code or performance (that's a refactoring task)

How It Works

Advisory only — output analysis and an optimized prompt. Do not execute the task.

Phase 1: Project Detection

Before analyzing the prompt, detect context from the working directory:

1. Read CLAUDE.md / AGENTS.md for project conventions
2. Detect tech stack from config files:
   • package.json → Node / TypeScript / React / Next.js
   • go.mod → Go
   • pyproject.toml / requirements.txt → Python
   • Cargo.toml → Rust
   • build.gradle / pom.xml → Java / Kotlin
3. Note the detected stack for component matching and missing-context analysis

If no project files found, flag "tech stack unknown" and proceed.

Phase 2: Intent Classification

Classify the user's task:

| Category | Signal Words | Example | |----------|-------------|---------| | New Feature | build, create, add, implement | "Build a login page" | | Bug Fix | fix, broken, not working, error | "Fix the auth flow" | | Refactor | refactor, clean up, restructure | "Refactor the API layer" | | Research | how to, what is, explore | "How to add SSO" | | Testing | test, coverage, verify | "Add tests for the cart" | | Review | review, audit, check | "Review my PR" | | Documentation | document, update docs | "Update the API docs" | | Infrastructure | deploy, CI, docker, database | "Set up CI/CD pipeline" |

Phase 3: Scope Assessment

| Scope | Heuristic | Approach | |-------|-----------|----------| | Trivial | Single file, < 50 lines | Direct execution | | Low | Single component or module | Single skill or tool | | Medium | Multiple components, same domain | Chained steps + verification | | High | Cross-domain, 5+ files | Plan first, then phased execution | | Epic | Multi-session, architectural shift | Multi-session plan with checkpoints |

Phase 4: Component Mapping

Map intent + scope to available agent components:

| Intent | Skills | Agents | |--------|--------|--------| | New Feature | dev, dev-frontend/backend, dev-scaffolding | planner, code-reviewer | | Bug Fix | dev-testing, dev-debugging | tdd-guide | | Refactor | dev-code-reviewer | code-reviewer | | Research | search, rag | explore agent | | Testing | dev-testing | test runner | | Review | dev-code-reviewer | code-reviewer | | Documentation | documentation | doc writer | | Infrastructure | dev-backend | architect |

For project-specific skills, check .agents/skills/ to find applicable ones.

Phase 5: Missing Context Detection

Scan the prompt for missing information:

• [ ] Tech stack — detected or needs user input?
• [ ] Target scope — files, directories, or modules specified?
• [ ] Acceptance criteria — how to know the task is done?
• [ ] Error handling — edge cases and failure modes addressed?
• [ ] Security requirements — auth, validation, secrets?
• [ ] Testing expectations — unit, integration, E2E?
• [ ] Existing patterns — reference files or conventions to follow?
• [ ] Scope boundaries — what to exclude?

If 3+ items are missing, ask the user up to 3 clarification questions before generating the optimized prompt.

Phase 6: Generate Optimized Prompt

Produce two versions:

Full version (inside a fenced code block):

• Clear task description with context
• Tech stack (detected or specified)
• Acceptance criteria
• Verification steps
• Scope boundaries (what to exclude)
• Relevant skills/agents to invoke

Quick version (one-liner patterns):

| Intent | Pattern | |--------|---------| | New Feature | Plan [feature]. Implement with tests. Review. Verify. | | Bug Fix | Write failing test for [bug]. Fix to green. Verify. | | Refactor | Refactor [scope]. Review. Verify no regressions. | | Research | Search for [topic]. Summarize findings with citations. | | Testing | Add tests for [module]. Target [coverage]% coverage. |

Prompt & Context Quality Principles

1. Specificity over vagueness: name files, modules, endpoints
2. Acceptance criteria: define "done" before starting
3. Scope boundaries: state what to exclude to prevent drift
4. Existing patterns: reference existing code the agent should follow
5. Verification step: end with a concrete check (test, build, curl)
6. Component awareness: invoke skills/agents by name when applicable
7. Context assembly: include relevant code, docs, and data — not just the question
8. Self-reflection: ask the model to verify its own reasoning (CoT) before final output
9. Treat prompts like code: version control prompts, run evals, iterate based on metrics
10. Tool-augmented prompting: when a prompt involves factual lookup, direct the model to use search/MCP tools rather than relying on training data

Output Format

### Prompt Diagnosis
**Strengths**: (what the original does well)
**Issues**: (table: issue | impact | fix)
**Needs Clarification**: (numbered questions)

### Recommended Components
(table: type | component | purpose)

### Optimized Prompt — Full
(fenced code block, ready to paste)

### Optimized Prompt — Quick
(one-liner)

### Enhancement Rationale
(table: what was added | why)

Constraints

• Advisory only — produce prompts, not implementations
• Respond in the same language as the user's input
• When referencing skills, verify they exist in .agents/skills/ first
• Keep optimized prompts self-contained and copy-pasteable