docs: initialize engineering starter kit

2026-06-28 09:40:40 +02:00
commit ed8efda692
23 changed files with 3131 additions and 0 deletions
@@ -0,0 +1,310 @@
+# 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.
+```