Agentic Engineering

Appearance

Operations Prompts ​

Ops prompts produce operable artifacts: pipelines, runbooks, dashboards hooks, release truth. Prefer dry-runs and plan mode before anything that touches production. Related playbooks: CI/CD case study patterns, Prototype to Production.

Documentation sync ​

Update docs to match the code — not the other way around.

Inputs: <code paths that changed>, <doc paths>, <audience>, <staleness symptoms>

text
Sync documentation to current code.

Code source of truth: <code paths that changed>
Docs to update: <doc paths>
Audience: <audience>
Known staleness: <staleness symptoms>

Rules:
- Code wins over docs. Fix docs; do not "fix" code to match old docs
  unless the doc describes an intentional contract and code drifted —
  in that case, flag the drift as a bug, don't silently rewrite the contract.
- Delete false docs; don't leave contradictory sections.
- Prefer short accurate pages over comprehensive fiction.
- Update command examples by actually checking package scripts / Makefile.

Deliver a diff of docs + a list of remaining doc gaps.

Expected output: doc PR diff, gap list, no speculative code changes.

Evaluate: Commands in docs work. No contradictory sections remain. Gaps are explicit. See Docs as Memory.

Variations:

  • Sync only CLAUDE.md / AGENTS.md.
  • Generate API docs from OpenAPI only.

Deployment ​

Prepare or execute a deployment with explicit preflight and rollback.

Inputs: <target environment>, <artifact / commit>, <preflight checks>, <rollback procedure>

text
Deployment task for <target environment>
Artifact/commit: <artifact / commit>
Preflight: <preflight checks>
Rollback: <rollback procedure>

Do:
1. Run/state preflight checks; STOP on failure.
2. Produce a step-by-step deploy plan (commands) matching our existing
   deploy docs/scripts — do not invent a new deploy system.
3. If I approve, execute only the approved steps.
4. Verify post-deploy health checks.
5. If verification fails, execute rollback and report.

Never skip rollback readiness. Never "force" past failing preflight
without my explicit override phrase.

Expected output: preflight results, plan, (optional) execution log, verify/rollback outcome.

Evaluate: Preflight real. Rollback tested or at least scripted. Health checks defined.

Variations:

  • Plan-only for production; execute only in staging.
  • Blue/green or canary steps required.

CI/CD pipeline ​

Add or harden pipeline jobs without cargo-culting.

Inputs: <CI system>, <required gates>, <repo commands>, <time budget>

text
Design/implement CI changes for <CI system>.

Required gates: <required gates>
Repo commands to reuse: <repo commands>
Time budget per PR: <time budget>

Requirements:
- Prefer existing scripts (package.json/Makefile) over inline shell novels.
- Fail fast on lint/type/unit; put slow suites in a separate job if needed.
- Cache dependencies the way this repo already does (or add one pattern).
- Secrets via the CI secret store — never commit tokens.
- Document how to run the same checks locally.

Out of scope: CD to production unless specified. No flaky `continue-on-error`
on required gates.

Expected output: pipeline config diff, local parity notes, gate list.

Evaluate: Gates match requirements. Local commands documented. No secret leakage. See Quality Gates.

Variations:

  • PR-only checks first; release workflow separate.
  • Required status checks matrix for monorepo packages.

Release notes ​

Generate accurate release notes from the diff — not marketing fluff.

Inputs: <from ref>, <to ref>, <audience>, <breaking-change policy>

text
Draft release notes from <from ref> → <to ref>
Audience: <audience>
Breaking-change policy: <breaking-change policy>

Process:
1. Inspect commits/PR titles and the diff summary.
2. Group: Features / Fixes / Breaking / Internal.
3. Call out migrations, config changes, and operator actions required.
4. Link key PRs/commits.
5. Flag uncertain items for human confirmation — do not invent user
   benefits that aren't in the diff.

Tone: factual. No "we're excited." Keep it scannable.

Expected output: grouped release notes + operator actions + uncertainty flags.

Evaluate: Every item maps to the diff. Breaking changes unmistakable. No hype.

Variations:

  • Customer-facing vs internal engineering notes (two outputs).
  • SECURITY section mandatory.

Runbook ​

Write an operable runbook for an incident class.

Inputs: <incident class>, <symptoms>, <systems involved>, <severity / paging>

text
Write a runbook for: <incident class>
Symptoms: <symptoms>
Systems: <systems involved>
Severity/paging: <severity / paging>

Sections required:
1. Symptoms & impact
2. Immediate actions (first 5 minutes)
3. Diagnosis steps (commands, dashboards, logs) with expected healthy vs bad
4. Mitigation / fix actions
5. Rollback
6. Escalation path
7. Post-incident notes to capture

Commands must be copy-pastable and match our actual tooling.
Do not invent dashboards that don't exist — mark gaps as TODO with owners.

Expected output: runbook markdown ready to commit under ops docs.

Evaluate: First-5-minutes is actionable. Commands are real. Gaps labeled, not faked.

Variations:

  • SEV1-only short form card.
  • Include customer-comms template.

Production readiness ​

Gate a feature/service before first production traffic.

Inputs: <feature or service>, <readiness checklist path or paste>, <environment>

text
Production readiness review for: <feature or service>
Environment: <environment>
Checklist: <readiness checklist path or paste>

Evaluate each checklist item: pass / fail / n/a — with evidence
(file path, dashboard, config).

Additionally assess:
- Rollback story
- Observability (logs/metrics/traces for critical path)
- Data migration safety
- Authz coverage on new endpoints
- Load/volume assumptions vs limits
- Feature flag defaults

Verdict: ready / not ready. Not ready requires a blocker list ordered
by severity. Do not implement fixes in this pass unless I ask.

Expected output: checklist with evidence, verdict, blocker list.

Evaluate: Evidence cited. "N/A" justified. Blockers are real ship-stoppers.

Variations:

  • Security-only readiness.
  • Multi-tenant isolation focus.

Observability instrumentation ​

Add logs/metrics/traces that operators can actually use.

Inputs: <critical path>, <existing telemetry libs>, <RED/USE or custom signals>, <cardinality limits>

text
Instrument observability for: <critical path>
Use existing libs: <existing telemetry libs>
Signals needed: <RED/USE or custom signals>
Cardinality limits: <cardinality limits>

Requirements:
- Structured logs with request/correlation IDs already used in-repo.
- Metrics with low-cardinality labels only — call out rejected high-cardinality ideas.
- Trace spans on external calls and DB boundaries.
- Error logs must not include secrets or PII (list fields you redacted).
- Document what dashboard/alert should consume each signal (or mark TODO).

Do not refactor business logic except for minimal instrumentation hooks.

Expected output: instrumentation diff + signal→dashboard/alert map + PII notes.

Evaluate: Cardinality safe. Correlation IDs present. No secrets in logs. Signals map to operator questions.

Variations:

  • Metrics only / tracing only.
  • Add SLO burn-rate alert sketch.

Incident postmortem draft ​

Turn an incident timeline into a blameless postmortem draft.

Inputs: <incident ticket>, <timeline notes>, <impact summary>, <systems>

text
Draft a blameless postmortem for incident <incident ticket>.

Impact: <impact summary>
Systems: <systems>
Timeline notes: <timeline notes>

Include:
1. Summary
2. Impact (users, revenue, duration)
3. Timeline (UTC)
4. Root cause (technical) + contributing factors
5. What went well / poorly in response
6. Action items with owners/dates (detect, mitigate, prevent)
7. Lessons that change process or architecture — not "be more careful"

Do not assign personal blame. Mark unknowns explicitly.
Do not implement action items here.

Expected output: postmortem draft with action items and explicit unknowns.

Evaluate: Root cause is technical. Action items are specific and owned. No blame language.

Variations:

  • Short form for SEV3.
  • Require at least one detection-improvement action.

A field manual for AI-native software engineering.