# Prompts

This file is a reusable engineering prompt library for humans and AI coding
agents.

Use these prompts together with [AGENTS.md](../AGENTS.md),
[PROJECT.md](PROJECT.md), [ARCHITECTURE.md](ARCHITECTURE.md), and
[CONVENTIONS.md](CONVENTIONS.md).

## Prompt Pattern

Strong prompts include:

- Objective.
- Relevant files, URLs, tickets, or logs.
- Constraints and non-goals.
- Expected output.
- Validation expectations.
- Whether the agent should implement, plan only, or review only.

## Feature Development

```text
Act as a senior software engineer in this repository.

Objective:
Implement {{FEATURE_NAME}}.

Context:
- Product goal: {{PRODUCT_GOAL}}
- Relevant docs: docs/PROJECT.md, docs/ARCHITECTURE.md, docs/CONVENTIONS.md
- Relevant files: {{RELEVANT_FILES}}

Requirements:
- {{REQUIREMENT_1}}
- {{REQUIREMENT_2}}

Non-goals:
- {{NON_GOAL_1}}

Before coding:
- Inspect the current implementation.
- Identify ambiguity.
- Ask concise questions if confidence is below 95%.

After coding:
- Run the strongest practical validation.
- Summarize changed files, validation, and residual risk.
```

## Bug Investigation

```text
Investigate this bug before changing code.

Observed behavior:
{{OBSERVED_BEHAVIOR}}

Expected behavior:
{{EXPECTED_BEHAVIOR}}

Evidence:
{{LOGS_SCREENSHOTS_OR_STEPS}}

Task:
- Reproduce or reason from available evidence.
- Identify the most likely root cause.
- Locate the affected code path.
- Propose the smallest maintainable fix.
- Implement only after the cause is understood.
- Add or update regression coverage where practical.
```

## Root Cause Analysis

```text
Perform a root cause analysis for {{INCIDENT_OR_DEFECT}}.

Include:
- Timeline.
- User impact.
- Technical trigger.
- Root cause.
- Contributing factors.
- Detection gap.
- Corrective actions.
- Preventive actions.

Separate confirmed facts from hypotheses.
Do not assign blame to individuals.
```

## Refactoring

```text
Refactor {{AREA}} to improve {{QUALITY_GOAL}}.

Constraints:
- Preserve behavior.
- Keep public contracts stable unless explicitly approved.
- Avoid broad unrelated cleanup.
- Follow docs/ARCHITECTURE.md and docs/CONVENTIONS.md.

Process:
- Inspect existing patterns.
- Identify tests or checks that protect behavior.
- Make small mechanical changes first.
- Run validation after meaningful steps.
- Summarize behavior-preservation evidence.
```

## Architecture Review

```text
Review the architecture of {{SYSTEM_OR_MODULE}}.

Use:
- docs/PROJECT.md
- docs/ARCHITECTURE.md
- docs/DECISIONS.md
- Relevant source files

Focus on:
- Boundary clarity.
- Dependency direction.
- Data ownership.
- Failure modes.
- Security assumptions.
- Operational complexity.
- Maintainability over the next {{TIME_HORIZON}}.

Return:
- Findings ordered by severity.
- Trade-offs.
- Recommended decisions or ADR updates.
```

## Security Review

```text
Perform a security review of {{SCOPE}}.

Focus on:
- Authentication.
- Authorization.
- Input validation.
- Output encoding.
- Secrets handling.
- Data exposure.
- Dependency risk.
- Logging of sensitive data.
- SSRF, injection, XSS, CSRF, path traversal, and insecure deserialization where relevant.

For each finding include:
- Impact.
- Exploitability.
- Evidence.
- Recommended fix.
- Validation strategy.
```

## Performance Review

```text
Review performance risk in {{SCOPE}}.

Include:
- Hot paths.
- Algorithmic complexity.
- Database query behavior.
- Caching behavior.
- Network calls.
- Rendering or UI bottlenecks.
- Resource usage.
- Measurement gaps.

Recommend improvements only when they are justified by evidence, constraints, or clear risk.
```

## Documentation

```text
Improve documentation for {{AREA}}.

Goals:
- Make setup and maintenance easier.
- Remove outdated or duplicated information.
- Add cross links to related docs.
- Keep one source of truth per topic.

Validate:
- Links are correct.
- Commands are current.
- Examples are realistic.
- The document is useful to a new contributor.
```

## API Design

```text
Design or review the API for {{CAPABILITY}}.

Include:
- Consumers.
- Resource or command model.
- Request and response shapes.
- Validation errors.
- Authorization rules.
- Idempotency.
- Pagination or filtering.
- Versioning.
- Backward compatibility.
- Observability.

Prefer stable contracts over exposing internal persistence models.
```

## Database Design

```text
Design or review database changes for {{CAPABILITY}}.

Include:
- Entities and ownership.
- Relationships.
- Constraints.
- Indexes.
- Migration strategy.
- Rollback strategy.
- Backfill needs.
- Data retention.
- Privacy concerns.
- Query patterns.

Do not implement destructive migrations without explicit approval.
```

## Test Generation

```text
Generate tests for {{SCOPE}}.

Use the repository's existing test patterns.

Cover:
- Happy path.
- Boundary conditions.
- Authorization or permission behavior when relevant.
- Error handling.
- Regression cases.

Avoid brittle tests that depend on incidental implementation details.
```

## Code Review

```text
Review the provided changes as a senior engineer.

Prioritize:
- Bugs.
- Security issues.
- Data loss risk.
- Behavioral regressions.
- Missing validation.
- Maintainability issues.

Return findings first, ordered by severity, with file and line references where available.
Keep summary secondary.
```

## Pull Request Review

```text
Review this pull request.

Use:
- PR description.
- Diff.
- Linked issue or requirement.
- Relevant project docs.

Assess:
- Whether the change solves the stated problem.
- Whether the implementation fits the architecture.
- Whether tests and validation match the risk.
- Whether rollout or migration notes are missing.

Return:
- Blocking findings.
- Non-blocking suggestions.
- Questions.
- Merge readiness.
```

## Technical Debt Review

```text
Assess technical debt in {{SCOPE}}.

Classify findings by:
- User impact.
- Engineering drag.
- Risk.
- Estimated effort.
- Suggested sequencing.

Do not recommend rewrites unless incremental improvement is clearly worse.
Prefer concrete next steps over broad critique.
```