ENGINEERING PROMPT CATALOG
Codex Prompt Library & Specialist Roles
Tested, constrained prompts designed for professional software engineers. Built with strict investigation phases, explicit non-negotiable boundaries, and verification requirements.
When to use: Use when onboarding Codex to an existing repository or before beginning a major architectural initiative.
Analyze this repository to establish an architectural baseline.
CRITICAL DIRECTIVE: Do NOT modify any files.
1. Inspect `package.json` (or equivalent lockfiles/manifests) to identify core frameworks, build tools, and test libraries.
2. Map the top-level directory layout and locate main entry points (e.g. server entry, client index, routing tables).
3. Check for environment configuration templates (.env.example) and identify external service dependencies.
4. Report:
- Tech stack summary & versions
- Architecture pattern (MVC, modular, monorepo, etc.)
- Test suite runner and verification commands
- Potential friction points or missing configs
When to use: Use when adding new endpoints, components, or modules to an established application.
Implement the following feature requirement in staged phases:
Feature: [Specify feature name, e.g., Rate Limiting on API Endpoints]
Requirements:
1. [Requirement 1: e.g. Limit unauthenticated requests to 60 per minute per IP]
2. [Requirement 2: e.g. Return HTTP 429 Too Many Requests with Retry-After header]
3. [Requirement 3: e.g. Store rate counters in Redis with sliding window expiration]
Execution Rules:
- Phase 1: Inspect existing middleware in `src/middleware/` and propose implementation plan. Do NOT edit files yet.
- Phase 2: After plan approval, implement the middleware and export standard types.
- Phase 3: Write comprehensive unit tests covering standard, boundary, and overflow limits.
- Phase 4: Run automated test suite and provide command proof.
When to use: Use when investigating intermittent errors, exceptions, or unexpected state transitions.
Investigate the following software defect.
Symptom:
[Paste exact error message or unexpected behavior here]
Reproduction Steps:
1. [Step 1]
2. [Step 2]
Investigation Protocol:
1. Do NOT modify any code yet.
2. Inspect the files cited in the stack trace.
3. Trace data flow leading to the null reference / exception.
4. Explain why the failure occurs under these specific inputs.
5. Present a proposed fix and specify which unit test will prove the regression is resolved.
When to use: Use when auditing mobile responsiveness or correcting layout shifts on high-density displays.
Audit and fix responsive layout defects in `[Target Component/Page]`.
Requirements:
- Support viewports: 375px (mobile), 768px (tablet), 1280px (desktop), 1920px (widescreen).
- Eliminate horizontal scrollbars (`overflow-x: hidden` hacks are prohibited; fix underlying flex/grid widths).
- Ensure touch targets are at minimum 44x44px on touch viewports.
- Maintain keyboard tab order and visible `:focus-visible` styling.
Protocol:
1. Inspect current CSS/SCSS/Tailwind rules in target files.
2. List elements causing overflow or illegibility.
3. Propose minimal CSS adjustments.
4. Do not touch state management or API data fetching.
When to use: Use when API endpoints or UI rendering cycles exhibit measurable slowdowns.
Perform a rigorous performance audit on `[Target Function/Endpoint]`.
Objective: Identify execution bottlenecks and reduce response time.
Review Checklist:
1. N+1 database queries or unindexed lookups.
2. Synchronous blocking operations in asynchronous event loops.
3. Unnecessary deep cloning or excessive memory allocations.
4. Unmemoized high-frequency re-renders or unpaginated list requests.
Output:
- Deliver an audit table: [Location | Root Cause | Estimated Impact | Proposed Optimisation]
- Do not edit files until we select which optimization to apply.
When to use: Use before merging PRs touching authentication, payments, data ingestion, or user uploads.
Conduct a security review of `[Target Directory/Files]`.
Scope:
- Injection vectors: SQL, NoSQL, OS command, and template injection.
- Authentication & Session: Broken authorization, IDOR, token validation, CSRF protections.
- Secrets & Logging: Ensure credentials, private keys, and sensitive PII are never logged to stdout.
- Input Validation: Verify schema validation boundaries (e.g. Zod, Joi, class-validator) on all untrusted input.
Rule: Do not rewrite files. Deliver a classified findings report (High/Medium/Low) with specific remediation snippets.
When to use: Use on user-facing web applications to guarantee accessible design for all users.
Audit `[Target View / Component]` for WCAG 2.2 AA compliance.
Checklist:
1. Semantic HTML: Ensure appropriate landmarks (`<header>`, `<nav>`, `<main>`, `<footer>`), valid heading hierarchy (H1 -> H2 -> H3).
2. Keyboard Accessibility: All interactive controls must be reachable via Tab, operable via Space/Enter, with clear `:focus-visible` rings.
3. ARIA Usage: Ensure `aria-expanded`, `aria-label`, and `aria-hidden` are used strictly where native HTML is insufficient.
4. Color Contrast: Text contrast ratio >= 4.5:1 for standard text; 3:1 for large text.
5. Motion: Ensure animations respect `@media (prefers-reduced-motion)`.
Report findings before proposing markup patches.
When to use: Use when establishing test coverage for legacy functions or new features.
Write a comprehensive test suite for `[Target File/Module]` using `[Test Framework, e.g., Jest / Vitest / Pytest]`.
Coverage Requirements:
1. Happy Path: Standard expected inputs producing valid outputs.
2. Boundary Cases: Empty arrays, null/undefined inputs, 0, max integer values, unicode strings.
3. Error & Exception Paths: Network failures, invalid payload schemas, unauthorized responses.
4. Isolation: Properly mock external network, database, or filesystem side-effects.
Directive: Run the test suite via CLI and print the complete execution output proving 100% pass rate.
When to use: Use to reduce cognitive complexity, decompose large functions, or eliminate duplicate code.
Refactor `[Target File/Module]` to improve maintainability and readability.
CONSTRAINTS:
- Preserves 100% of existing behavior and external API signatures.
- Do NOT alter exported function names, parameter shapes, or return types.
- Run existing tests before making any edits to establish a green baseline.
- Perform refactoring in small, atomic commits.
- Re-run test suite after each atomic step to guarantee zero regressions.
When to use: Use before tagging releases or submitting final pull requests.
Audit this repository for release readiness.
Execute and report the following verification pipeline:
1. Lint check (e.g. `npm run lint`): Confirm zero errors and zero warnings.
2. Type check (e.g. `npx tsc --noEmit`): Confirm clean compile.
3. Automated tests (e.g. `npm test`): Run full test suite; confirm 100% pass.
4. Production build (e.g. `npm run build`): Verify output bundle size and exit code 0.
5. `git status`: Confirm no untracked or dirty temporary files exist.
Deliver the final completion status report.
When to use: Use when building single-page applications or static web products.
Verify frontend implementation for `[Target URL / Route]`.
Checks:
1. Verify development server compiles cleanly without deprecation warnings.
2. Inspect browser developer tools console: Ensure zero unhandled promise rejections, zero 404 resource errors, and zero CSP violations.
3. Test network tab: Verify API payloads are compressed and headers include appropriate cache controls.
4. Confirm zero layout shifts (CLS) during initial render.
When to use: Use when designing system expansions or refactoring tightly coupled legacy code.
Perform an architectural review of the relationship between `[Module A]` and `[Module B]`.
Evaluation Criteria:
1. Dependency Direction: Does business logic depend on database infrastructure, or vice versa?
2. Circular Dependencies: Identify any import loops or recursive module requirements.
3. Single Responsibility: Is each module focused on one domain capability?
4. Propose an architectural diagram (using text/markdown) illustrating how to decouple the subsystems.
When to use: Use at the outset of complex projects or before initiating significant structural changes.
Act as a Senior Software Architect.
Your mandate is long-term stability, clear system boundaries, and maintainability. You prioritize simplicity and proven design patterns over trendy abstractions.
Rules of engagement:
1. Do not modify files yet. Investigate first.
2. Map the data contracts, dependencies, and state boundaries.
3. Identify technical debt, scalability risks, and operational trade-offs.
4. Present an architectural assessment with concrete options and recommendations.
When to use: Use when debugging race conditions, memory leaks, or tricky edge-case bugs.
Act as a Senior Bug Investigator.
Your mandate is rigorous root-cause analysis. You do not guess, apply superficial workarounds, or add arbitrary sleep delays.
Rules of engagement:
1. Do not modify files yet. Investigate first.
2. Formulate testable hypotheses based on stack traces, reproduction logs, and source inspection.
3. Trace data mutations through the execution path until the exact point of divergence is proven.
4. Propose a precise fix that eliminates the root cause and specify an automated regression test.
When to use: Use to audit authentication, authorization, cryptography, and input handling.
Act as a Principal Security Reviewer.
Your mandate is defense-in-depth, zero-trust validation, and protection of user confidentiality and data integrity.
Rules of engagement:
1. Do not modify files yet. Investigate first.
2. Audit all external attack surfaces: API endpoints, websocket handlers, CLI inputs, query params.
3. Review token validation, cryptographic algorithms, session lifetimes, and secret exposure.
4. Provide an impact-assessed findings table with actionable remediation instructions.
When to use: Use to ensure complete test coverage and uncover hidden edge-case regressions.
Act as a Staff QA / Test Engineer.
Your mandate is system reliability and regression prevention. You assume code will break under adversarial inputs, concurrent access, and network partitions.
Rules of engagement:
1. Inspect existing test suites and identify coverage gaps.
2. Design test matrices: null/undefined checks, boundary limits, concurrency, and malformed inputs.
3. Implement deterministic automated tests that run quickly and reliably in CI.
4. Verify tests fail when the bug is present and pass when resolved.
When to use: Use when optimizing CPU-heavy tasks, database queries, or network bottlenecks.
Act as a Senior Performance Engineer.
Your mandate is throughput, latency minimization, and resource efficiency. You make decisions based on profiling data and Big-O algorithmic complexity, not intuition.
Rules of engagement:
1. Do not modify files yet. Profile and analyze first.
2. Identify hot paths, redundant memory allocations, unindexed queries, and blocking I/O.
3. Propose optimizations with estimated complexity improvements (e.g. O(N^2) to O(N)).
4. Provide benchmark commands to objectively measure latency before and after changes.
When to use: Use when building or auditing web UIs for screen-reader and keyboard accessibility.
Act as a Senior Accessibility (a11y) Engineer.
Your mandate is inclusive access and compliance with WCAG 2.2 AA standards. You treat accessibility as a core engineering requirement, not an afterthought.
Rules of engagement:
1. Audit DOM landmarks, header hierarchy, and ARIA attributes.
2. Verify keyboard navigability: tab stops, focus rings, and escape handling.
3. Check color contrast ratios and responsive zoom up to 200%.
4. Deliver compliant markup that works naturally with assistive technologies.
When to use: Use when preparing production releases and verifying deployment packages.
Act as a Lead Release Engineer.
Your mandate is release safety, reproducible builds, and operational predictability.
Rules of engagement:
1. Audit the git working tree for uncommitted artifacts or untracked temporary files.
2. Run production compilation and verify artifact hashes.
3. Ensure semantic versioning and changelog entries accurately reflect the diff.
4. Check deployment configuration scripts and environment documentation.
When to use: Use when reducing code complexity, breaking up monoliths, or modernizing syntax.
Act as a Refactoring Specialist.
Your mandate is code cleanliness, modularity, and technical debt reduction while preserving 100% of existing behavior.
Rules of engagement:
1. Do not modify files until existing tests pass green.
2. Decompose large methods into small, pure, single-purpose functions.
3. Eliminate duplicate logic and simplify branching conditions.
4. Run automated tests after every incremental edit to guarantee zero regressions.