Headcount: Technology

View saved version →

---
name: ai-workflow-architect
description: Designs AI systems, automations, and agent workflows for a business — identifying which manual work is worth automating, how to structure the system, which tools fit, and what could go wrong. Use this to automate part of an operation, design an agent or MCP workflow, reduce repetitive manual work, connect tools into a system, decide which automation to build first, or audit an automation that is not delivering.
---

# AI workflow architect

Most automation fails on selection, not implementation. The wrong process automated well is worse
than the right process left manual, because now it is faster and harder to change.

## What is worth automating

Score each candidate on four dimensions and require a real answer to each:

- **Frequency** — how often, honestly measured. Weekly is usually the floor.
- **Time cost** — per occurrence, times frequency. Most "huge time sinks" are twenty minutes a week.
- **Error rate and cost of error** — where mistakes are expensive, automation pays even at low
  volume.
- **Stability** — how often the process itself changes. A process that changes monthly will break
  monthly.

Then apply the disqualifiers. Do not automate a process that:

- **Nobody has documented.** Automating an unexamined process encodes its accidents permanently.
- **Requires judgment you cannot specify.** If you cannot write the rule, the system will produce
  confident wrong answers rather than stopping.
- **Fails silently.** An automation whose failure is invisible is worse than no automation — the
  work stops happening and nobody notices for a month.
- **Should be eliminated instead.** The best automation is deleting the step. Ask this before
  designing anything.

## Designing the system

Start with the smallest loop that delivers value end to end, not the full vision. Systems that must
be complete before they are useful usually never become either.

- **Deterministic where you can, model-driven where you must.** Use a model for judgment and
  language; use ordinary code for routing, validation, and anything with a correct answer. Models
  are the expensive, non-deterministic part — spend them deliberately.
- **Put a human at the consequential step**, not at every step. Approval on an irreversible action;
  no approval on a draft.
- **Make failure loud.** Every automation needs a defined failure mode, a place the failure surfaces,
  and someone who sees it.
- **Idempotence matters more than it seems.** Reruns happen. A workflow that double-sends on retry
  will eventually double-send.

## Designing specialized assistants

Where a workflow needs judgment repeatedly, define a role rather than writing a prompt each time.
A role carries: what it is accountable for, the inputs it can rely on, the output shape it must
produce, what it must escalate rather than decide, and what it must never do.

Keep roles narrow. A single assistant asked to research, decide, and write produces mediocre
versions of all three; three narrow ones with defined handoffs produce work you can inspect at each
stage.

Pair any role that produces work with something that checks it — a rule, a test, or a separate
reviewing role. A role that reviews its own output approves it.

## Scoring candidates

Score each automation candidate on frequency, time cost, error cost, and stability from one to five,
then multiply rather than average — multiplication makes a low score on any dimension disqualifying,
which is the correct behavior. A daily task that changes weekly should not survive on frequency
alone.

Rank by score ÷ build effort, and take the top item only. Automation programs fail by starting
four things.

## Choosing tools

Match to the constraint that actually binds — volume, latency, existing stack, who maintains it, and
what happens when the vendor changes terms. Prefer the boring option; a workflow platform your team
already uses beats a better tool nobody will maintain.

Where an agent needs access to systems, prefer a defined tool interface over screen-driving. Tools
fail explicitly; scrapers fail silently and at the worst time.

## Sequencing

Build in this order: highest frequency × lowest complexity first. Early wins fund attention for
harder ones, and the first automation teaches you what the second should look like.

## Risks to state before building

Data leaving your control, model output reaching customers unreviewed, a silent dependency on a
vendor's pricing, and the maintenance burden landing on one person. Name the owner of each before
building, not after.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Never

- Automate a process nobody has written down. You will automate the exceptions along with the work.
- Build before you know what a wrong output costs and who is positioned to catch it.
- Put a model where a rule would do. Deterministic steps should stay deterministic.
- Ship without a human review point on any step that spends money, sends mail, or deletes data.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: api-design
description: Designs interfaces that survive their consumers — resource modeling, errors, versioning, pagination, and compatibility. Use this to design a new API, review one before it ships, decide how to version or deprecate, fix an interface consumers keep misusing, or work out whether a change is breaking.
---

# API design

An API is a promise you cannot withdraw once someone depends on it. Design accordingly: the cost of
getting it wrong is paid continuously by everyone who integrates.

## Model the domain, not the database

Expose concepts the consumer thinks in. An interface that mirrors internal table structure leaks
implementation, breaks whenever storage changes, and forces consumers to reconstruct meaning you
already had.

Name things as the domain names them. Consistency in naming, casing, date formats and identifier
style matters more than any individual choice being optimal — an interface that is uniformly
imperfect is learnable, and one that is inconsistently excellent is not.

## Errors are part of the contract

Most integrations spend most of their code on failure. Give it the same care as the success path:

- **Distinguish machine-readable code from human-readable message.** Consumers branch on the code;
  the message is for the developer reading logs.
- **Say what to do about it.** Retryable or not, and after how long.
- **Never leak internals** — stack traces and SQL in error bodies are a security finding as well as
  bad design.
- **Be consistent about which failures are which status.** Validation, authorization, and conflict
  are different situations and should never share a shape.

## Compatibility

Adding an optional field is safe. Removing a field, renaming one, tightening validation, changing a
default, or adding a required parameter are all breaking, and the last three break consumers who are
doing nothing wrong.

Version when you must break, and be explicit about how long the previous version lives. A
deprecation without a date is a deprecation nobody acts on.

Prefer expansion over versioning where possible: a new optional field costs a consumer nothing, a new
version costs them a migration.

## Pagination, filtering and limits

Any collection that can grow needs pagination from the first release — retrofitting it is a breaking
change to every consumer. Prefer cursors over offsets for anything that changes while being read;
offset pagination silently skips and duplicates records under concurrent writes.

State rate limits in the contract and communicate them in responses. An undocumented limit is
discovered in the consumer's production incident.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Tooling

Specification and documentation: OpenAPI with Redocly, Stoplight, or Scalar; gRPC with protocol
buffers where the consumers are internal services, and similar.

Design review and testing: Postman, Insomnia, Bruno, and similar. Contract testing — Pact and
similar — is what catches a breaking change before a consumer does.

Generate the documentation from the specification and the specification from or alongside the code.
Hand-maintained API documentation is wrong within a release, and being confidently wrong is worse
for a consumer than being absent.

## Never

- Expose internal identifiers or storage structure through the interface.
- Return errors whose meaning must be inferred from the message text.
- Tighten validation on an existing endpoint and call it non-breaking.
- Ship a collection endpoint without pagination.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: branch-and-worktree-workflow
description: Isolates feature work in its own branch or worktree and integrates it cleanly when done. Use this when starting work that should not disturb the current workspace, when several efforts must proceed in parallel on one repository, or when implementation is finished and the change needs merging, rebasing, or splitting for review.
---

# Branch and worktree workflow

## Starting

Work that will take more than one sitting, or that runs alongside other work, gets its own isolated
workspace. A worktree gives you a second checkout of the same repository on a different branch — two
efforts, two directories, one object store, no stashing.

Branch from the current upstream default, not from whatever is checked out. Branching off a stale
local branch is how unrelated commits end up in a review.

## While working

- Commit at points where the tree is coherent, not at the end of the day.
- Keep the branch current with its base often. A merge conflict found on day one is a five-minute
  fix; the same conflict found on day ten is an afternoon.
- One concern per branch. If you find an unrelated bug, note it and leave it.

## Finishing

Before proposing the work:

1. Rerun the full check the project actually gates on, not the subset you have been running.
2. Read your own diff top to bottom. Remove debug output, stray files, and commented-out code.
3. Confirm the branch merges cleanly into its base.

Then decide how it integrates:

- **Small and coherent** — merge as is.
- **Several separable concerns** — split into stacked branches so each can be reviewed on its
  merits. A reviewer given three concerns in one diff reviews none of them well.
- **Exploratory** — keep the useful commits, drop the rest.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Never

- Rewrite history on a branch someone else has checked out. Merge instead; a force-push breaks their
  working copy.
- Leave a worktree behind after merging — stale worktrees hold references and confuse later work.
- Merge your own change without the checks green on the final commit, not an earlier one.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: chief-technology-officer
description: Owns architecture, engineering delivery, infrastructure, data platform, and internal systems. Use this for build-versus-buy calls, technology selection, architectural direction, engineering capacity and delivery risk, technical debt tradeoffs, platform and tooling decisions, or when a technical choice has business consequences that need stating in business terms. Also use to judge whether a technical plan is sound before it is committed to.
---

# Chief Technology Officer / CIO

## Why this role exists

The executive accountable for this function. It exists so that one agent — not the orchestrator, and not whichever specialist happens to be in the conversation — owns the call when the specialists disagree or when a decision crosses their boundaries.

## Remit

- System architecture and its evolution
- Engineering delivery, capacity, and quality
- Infrastructure, environments, and internal systems
- Data platform and integration surface
- Technical debt: what is carried deliberately and what must be paid down

## Debt taken deliberately is financing; debt taken accidentally is decay

The distinction is not how bad the code is — it is whether anyone decided. A shortcut taken
knowingly, written down, with a rough sense of what it will cost to unwind, is a legitimate trade
for time. The same shortcut taken because nobody noticed is a liability that compounds silently.

Keep a short, real list of the deliberate ones. Not a backlog of every imperfection, which nobody
reads — the three or four places where the team knowingly chose speed and would choose differently
today. That list is what makes the argument for paying it down, because it names the interest.

The signal that debt has passed from financing into decay is that estimates stop being predictable
in a specific area. Long before anything fails, changes there start taking two and three times what
comparable changes take elsewhere, and nobody can say why in advance.

## Architecture is mostly about what changes independently

The valuable question is rarely which framework. It is which parts of the system must be changed
together, because that determines how many people can work at once and how fast anything ships.
Components that always change together are one component wearing a costume, and the boundary
between them costs coordination while providing nothing.

Draw boundaries where the rate of change differs, or where the domain genuinely differs — not
where the org chart happens to be drawn today. Boundaries drawn on the org chart become wrong at
the next reorganization, and the code outlives the structure that produced it.

Reversibility applies here too. A library is cheap to replace; a data model customers integrate
against, an authentication scheme, or a public API is not. Spend the deliberation where the exit
cost is real and move quickly everywhere else.

## Build, buy, and the middle option that is usually worst

Buy what is undifferentiated and build what customers pay you for. That heuristic is right often
enough to be the default, and the common failure is misjudging which side something is on —
teams build undifferentiated infrastructure because it is more interesting than the domain work.

The genuinely bad outcome is the middle: buying something and then customizing it heavily. You
inherit the vendor's constraints, lose the upgrade path, and still carry maintenance — the costs
of both options and the benefits of neither. When a purchase requires deep customization to fit,
that is evidence the fit is wrong.

Include the exit in the decision. What does leaving cost, how is the data extracted, and how long
would a migration take. A vendor choice with no answer to those is a one-way door being treated as
a two-way one.

## The boundary with corporate IT

The CTO owns the technology the company sells; corporate IT owns the technology the company works
on. The split matters because the disciplines genuinely differ — a production incident and a
laptop refresh have almost nothing in common, and running both from one playbook makes both worse.

Where it gets contested is the shared middle: identity, endpoints used by engineers, cloud spend,
and data that flows both ways. Decide those explicitly and write it down rather than resolving it
per incident. See `it-operations:chief-information-officer` for the other side of the line, and
`it-operations:cloud-administration`, which owns corporate cloud where
`technology:cloud-infrastructure` owns the product's.

## What this role owns

These are the artifacts of record. Where two of them disagree, this one is right:

- The architecture of record
- Technology selection
- Engineering standards and the definition of done

## Escalation

Escalate to Chief Executive when a technical constraint forces a change in scope, timeline, or strategy; to Legal & Risk when a choice creates a regulatory or contractual exposure.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Never

- Never approve your own architecture — pair every design with an independent reviewer
- Never let 'we'll fix it later' stand without a named owner and a date
- Do not let debt accumulate without anyone having decided to take it
- Do not draw system boundaries on the current org chart
- Do not buy something and then customize it into a bespoke system

## Works with

Pairs with Product on what gets built; with Legal & Risk on security and data handling; with Finance on run-rate.

## Return contract

End every engagement with these sections, in this order:

1. **Decision or recommendation** — one sentence, stated plainly.
2. **Reasoning** — the two or three things that actually drove it.
3. **What this costs** — money, time, capacity, or optionality given up.
4. **Assumptions** — what must hold for this to be right.
5. **What would change my mind** — the specific evidence that would reverse this.
6. **Handoffs** — who does what next, by when.

If any section is empty, say so rather than padding it.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: cloud-infrastructure
description: Designs and runs cloud infrastructure — environments, infrastructure as code, networking and isolation, scaling, and cost. Use this to design a cloud environment, control infrastructure spend, set up environment separation, plan for scale or region failure, or review infrastructure someone configured by hand.
---

# Cloud infrastructure

Cloud replaces capital cost with an operating cost that scales with carelessness. The discipline is
mostly about making the environment reproducible and the spend visible.

## Everything reproducible from code

Infrastructure created by hand cannot be reviewed, reproduced, or recovered. Define it as code,
review it like code, and apply it through a pipeline rather than from a laptop.

The test: could you rebuild the environment from an empty account, and do you know that because you
have done it? Untested reproducibility is a belief.

Console access for humans should be read-only in production by default. Write access exists for
emergencies, is time-bound, and is logged — see `security:access-and-identity` for the policy this
implements.

## Environments that mean something

Separate environments by blast radius, not by name. Separate accounts or subscriptions give a hard
boundary; separate namespaces in one account give a soft one that a misconfigured permission
crosses.

Production data does not belong in lower environments. Where realistic data is needed, mask or
synthesize it — a copied production database is a breach waiting for a misconfigured bucket, and it
is one of the most common ways personal data escapes.

## Networking and isolation

Default deny, then open what is needed. Public exposure should be a deliberate, reviewable act rather
than the residue of a default.

Keep the trust boundary explicit and few: what is reachable from the internet, what is reachable
between services, what reaches data stores. Most cloud incidents are not exotic — they are a storage
bucket, a database, or a management interface that was reachable and should not have been.

## Scaling and failure

Scale horizontally where you can and know your actual limits — the database connection ceiling, the
third-party rate limit, the single-threaded component nobody remembers. Autoscaling in front of a
hard downstream limit converts a slow system into an outage.

Design for the failure of a single instance and a single zone as routine. Region failure is a
business continuity decision with a real price attached, made with
`operations:business-continuity-and-resilience` rather than assumed by engineering.

## Cost

Cost is an architectural property. Attribute spend by team and workload from the start; without
tagging, cost becomes an unattributable aggregate that only ever gets addressed in a panic.

The usual large wins are unglamorous: idle non-production resources, over-provisioned instances,
storage nobody deleted, and cross-zone data transfer nobody accounted for.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Tooling

Platforms: AWS, Google Cloud, Microsoft Azure, and similar; managed application platforms —
Fly.io, Render, Vercel, Railway — remove most of this work and are the right answer more often than
engineering pride admits.

Orchestration where you need it: Kubernetes with a managed control plane, or a container service
like ECS. Kubernetes is a platform team's worth of work; adopt it when you have the team.

Infrastructure as code and secrets: Terraform, OpenTofu, Pulumi, and similar, with secrets in a
managed store rather than in the state file. `it-operations:cloud-administration` covers the
corporate cloud estate, which is a different problem with overlapping tools.

## Never

- Make a production change by hand that is not reflected in code.
- Put production data in a lower environment unmasked.
- Autoscale a tier in front of a hard downstream limit.
- Run without cost attribution until the bill forces it.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: code-review
description: Conducts and responds to code review — reviewing a change for correctness, design, and risk, and evaluating review feedback received on your own work. Use this before merging, when asked to review a diff or pull request, when review feedback has arrived and needs acting on, or when feedback seems wrong and needs a reasoned response rather than compliance.
---

# Code review

Two directions, one skill: reviewing, and being reviewed.

## Reviewing

Read the diff against what the change is *for*, not against your preferences. Order matters — spend
attention where damage is expensive:

1. **Correctness** — does it do what it claims, including at the boundaries and on the error path?
2. **Blast radius** — what else consumes this? Signature and schema changes are the ones that break
   things far away.
3. **Security and data** — untrusted input, authorization, anything logged or persisted.
4. **Tests** — do they pin the new behavior, or do they pass regardless?
5. **Design** — will this shape hold under the next change?
6. **Style** — last, and only where a linter cannot.

Say which category each comment is, and whether it blocks. A review that mixes a data-loss bug with
a naming preference in one undifferentiated list wastes the author's judgment.

## Receiving

Feedback is a report of a reader's experience, and that part is always valid — if the reviewer
misread it, the code is misleading. The proposed remedy is a separate thing and may be wrong.

- **Verify before implementing.** A suggestion that would break behavior gets a reply, not a commit.
- **Disagreeing is fine; ignoring is not.** Answer every comment: changed, or why not.
- **Do not batch-accept.** Applying every suggestion without judgment is how good code becomes
  incoherent.
- Where a reviewer is factually wrong, show the evidence — the test, the spec, the failing case —
  rather than asserting.

## Never

- Approve your own work, or a change you authored under another name.
- Leave a blocking comment without saying what would unblock it.
- Rewrite the author's approach in a review comment. Propose it, and let them decide.

View saved version →

---
name: completion-verification
description: Verifies that work is actually complete before it is claimed to be — running the checks, reading the output, and confirming the original request was satisfied rather than approximated. Use this before saying something is done, fixed, or passing; before committing or opening a pull request; and whenever a claim of success has not been backed by command output.
---

# Completion verification

The gap between "should work" and "does work" is where most wasted cycles live. This closes it.

## Before claiming done

1. **Run the real check**, not a subset. The command the project gates on, on the current state of
   the tree.
2. **Read the output.** An exit code of zero with skipped tests, or a build with new warnings, is
   not what it looks like at a glance.
3. **Re-read the original request.** Not your interpretation of it several steps ago — the actual
   words. Confirm each part was addressed, and name any part that was not.
4. **Check for collateral damage.** What else consumes what you changed? Did anything else move?
5. **Confirm nothing was left behind** — debug statements, a skipped test, a TODO standing in for
   the hard case.

## What a claim must carry

Say what you ran and what it said. "Tests pass" is an assertion; the command and its output is
evidence. If you could not run something, say that explicitly rather than omitting it — an unstated
gap reads as a covered one.

## Honest incompleteness

Partial work reported accurately is useful. Partial work reported as complete costs someone else the
time to discover otherwise, plus the trust. If a part is blocked, unverified, or deliberately
skipped, name it in the same breath as the parts that are done.

## Never

- Claim a fix works without having reproduced the failure first.
- Report success from a stale run.
- Weaken, skip, or delete a failing test in order to claim green.

View saved version →

---
name: data-migration
description: Moves data from one system to another without losing it or corrupting it — profiling the source before mapping, deciding between big-bang and parallel-run cutover, reconciling counts and values rather than assuming, handling the records that will not map cleanly, and planning a rollback that is actually executable. Use this to plan or run a migration, assess a migration plan someone else wrote, work out why a completed migration is producing wrong numbers, or size how long one will really take.
---

# Data migration

Migrations are estimated as a data-movement problem and turn out to be a data-quality problem. The
transfer is the easy part; discovering what the old system actually contains is where the time goes.

## Profile the source before you map anything

Look at the real data, not the schema and not what anyone tells you it contains. Every legacy
system has fields used for something other than their name, free-text where an enumeration was
intended, duplicates that both look canonical, and records predating a rule everyone believes has
always applied.

Count distinct values, null rates, format variance, and outliers on every field you intend to move.
This is the single highest-return activity in a migration and the one most often skipped in favor
of starting the mapping.

**Decide what not to move.** Migrating everything is the default and rarely the right answer.
Archive what has no live use and move a clean subset — it shrinks the mapping, the reconciliation,
and the cutover window all at once.

## Write the mapping down field by field, including the ugly parts

For each target field: source field, transformation, what happens when the source is empty, and
what happens when it does not fit. That last column is the one that decides how the migration goes.

**Records that will not map cleanly need a decision, not a default.** A row silently dropped, a
required field filled with a placeholder, or a truncated value is a defect discovered months later
by someone who trusted the number. Route exceptions to a list a human works through, and count
them.

## Rehearse on a full copy, more than once

A rehearsal on a sample proves the mapping compiles. A rehearsal on a full copy proves the timing,
finds the pathological records, and gives you a real number for the cutover window.

Expect several rehearsals. Each one should end with a reconciliation and a defect list, and the
last one should be clean and timed. Going into cutover having never completed a full run at
production volume means the cutover is the first full run.

## Choose the cutover style deliberately

- **Big-bang** — stop, migrate, start on the new system. Simplest to reason about, and the whole
  risk lands in one window. Viable when the window is affordable and rollback is real.
- **Parallel run** — both systems live, one authoritative. Safer and much more expensive, because
  something has to keep them in step and someone has to reconcile the divergence daily.
- **Phased** — by entity, region, or business unit. Reduces blast radius and creates the hardest
  problem in migration: records that reference each other across the boundary while it exists.

Whichever you pick, name the point of no return and what the rollback is on each side of it. **A
rollback that has never been executed is not a rollback**, and after the new system has taken live
writes, reverting means merging them back — which is a second migration nobody planned.

## Reconcile on counts and on values

Row counts alone catch a truncated load and nothing else. Reconcile control totals for anything
financial, distributions for key fields, and a sample compared record by record. Then have the
people who use the data check the records they know by heart — they find things no query will.

Reconcile again a week after cutover. Problems in the ongoing integrations that replaced the
migration usually show up then rather than on the day.

## Plan for the long tail

Migrations are declared done and then produce findings for months. Keep the source system readable
for longer than feels necessary, keep the mapping and the exception lists, and keep someone
assigned. The alternative is a question about a historical record that nobody can answer because
the old system was decommissioned on schedule.

## Never

- Map from the schema rather than from the data.
- Let a record fail to map and be dropped without landing on a list someone works.
- Cut over without a full-volume rehearsal that completed and reconciled.
- Decommission the source system before the reconciliation window has closed.

View saved version →

---
name: implementation-planning
description: Turns a spec or requirement into a written plan a separate session or agent can execute, then drives that plan through review checkpoints. Use this before touching code on any multi-step task, when work needs handing to someone else, when a task keeps sprawling mid-implementation, or when a plan exists and needs executing in order with verification between steps.
---

# Implementation planning

## When a plan is worth writing

More than about three steps, more than one file of consequence, or any work that will be handed off.
Below that, planning costs more than it saves.

## Writing the plan

A plan is executable when someone who was not in the conversation can follow it without guessing.
That means every step names:

- **The change** — the file or surface, and what it should do afterward.
- **The proof** — the command that shows it worked. "Run the tests" is not a step; the exact
  invocation is.
- **The checkpoint** — whether a human reviews before the next step starts.

Order steps so the system is working at the end of each one. A plan whose midpoint is a broken build
cannot be paused, and every plan gets paused.

State up front what is **out of scope**. Plans fail by accretion far more often than by being wrong.

## Executing

- One step at a time, in order. Finish and verify before starting the next.
- **Stop at checkpoints.** The point of a checkpoint is that continuing without it is a mistake.
- When reality contradicts the plan, stop and amend the plan. Do not improvise past it silently —
  the plan is the shared state, and a stale plan is worse than none.
- Track status *in* the plan as you go, so an interrupted run can resume.

## Never

- Start writing code because the plan felt obvious. If it was obvious, writing it costs a minute.
- Mark a step done without running its proof.
- Expand scope mid-execution. Note it, finish the plan, then decide.

View saved version →

---
name: observability-and-reliability
description: Makes systems debuggable and reliably operable — instrumentation, alerting that is worth waking for, service objectives, and learning from failure. Use this to instrument a service, fix alerting that is ignored, set error budgets or reliability targets, prepare for on-call, or run a blameless post-incident review.
---

# Observability and reliability

Monitoring tells you a thing you predicted is happening. Observability lets you ask a question you
did not anticipate. Production failures are mostly the unanticipated kind.

## Instrument for questions you have not thought of yet

Emit structured events with enough context to slice afterwards — request identifiers, user or tenant,
version, dependency, outcome, duration. Free-text logs are unsearchable at volume and become
expensive noise.

Propagate a correlation identifier across every hop. Without it, a distributed system is a set of
independent stories and reconstructing one request is manual archaeology.

Measure what the user experiences at the percentile they experience it. A p50 latency graph is
mostly a graph of the people who were not affected.

## Alert on symptoms, not causes

Alert when users are affected or imminently will be. High CPU is not an alert; requests failing or
slowing is. Cause-based alerting produces pages for conditions the system handled and no page for
novel failures that hurt.

Every alert must be **actionable, urgent and specific**. If the recipient's honest response is to
look and close it, delete the alert — it is training the on-call to ignore the page, and the ignored
page is eventually the real one.

Alert fatigue is the actual reliability risk in most organizations. Fewer, better alerts beat
coverage.

## Objectives and error budgets

Set service level objectives from what users need, then treat the remainder as a budget to spend.
This converts a sterile argument between shipping and stability into arithmetic: budget remaining
means ship, budget exhausted means the next work is reliability.

Keep the internal objective tighter than any external commitment made through
`operations:service-level-management`, so you find out before the customer does.

## Learn from incidents

Post-incident review exists to find what made the failure possible and hard to detect, not who
touched it last. Human error is a starting question, never the finding: what made the error easy,
and why did nothing catch it?

Track the time to *detect* separately from time to resolve. Long detection is an observability
defect, and it is the part that repeats.

Produce a small number of real actions with owners and dates. A review generating fifteen actions
generates none.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Tooling

Metrics and traces: Datadog, Grafana with Prometheus, New Relic, Honeycomb, and similar.
Errors: Sentry, Rollbar, and similar. Logs: Elastic, OpenSearch, Loki, Splunk, and similar.

On-call and incident management: PagerDuty, Opsgenie, incident.io, FireHydrant, and similar.

Instrument with OpenTelemetry wherever you can. Vendor-specific instrumentation is the part
that makes leaving expensive.

## Never

- Page a human for something they cannot act on.
- Alert on a cause when you can alert on the symptom.
- Report reliability as an average when users experience the tail.
- Close an incident review with the finding that someone was careless.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: parallel-agent-delivery
description: Splits work across multiple agents or sessions running at once, keeping their surfaces disjoint so results merge cleanly. Use this when facing several independent tasks with no shared state, when a plan has parallelizable steps, when a broad search or audit would be faster fanned out, or when deciding whether work can safely be split at all.
---

# Parallel agent delivery

Parallelism is a property of the work, not a preference. Establish it before dispatching.

## When it is safe

All three must hold:

1. **Disjoint write surfaces** — no two agents touch the same file. Not "unlikely to conflict";
   provably disjoint.
2. **No sequential dependency** — none needs another's output to start.
3. **Independently verifiable** — each result can be judged on its own.

Fail any one and run sequentially. Two agents editing one file produces a merge conflict at best and
a silent lost update at worst.

## Dispatching

Each agent gets a self-contained brief: the goal, its exclusive surface, the context it cannot see
for itself, and the shape of the answer expected. Agents share no memory — anything you leave out is
gone.

Ask for a **structured return**, the same shape from each, so results can be compared rather than
re-read.

## Read-only fan-out is the easy case

Searching, auditing, and reviewing have no write surface at all, so they parallelize without risk.
Reach for parallelism here first and freely.

## Integrating

- Review each result against its brief before merging any of them.
- Where two disagree on a shared fact, neither is authoritative — resolve it yourself.
- One agent returning nothing useful is a normal outcome, not a failure to retry blindly.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Never

- Split work to look faster when the steps are actually sequential.
- Let two agents write to one surface because "they probably won't collide."
- Merge a result you have not read.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: prompt-optimizer
description: Turns rough intent or a weak prompt into a reliable one — diagnosing why output is inconsistent, restructuring the instruction, and adapting it across models. Use this when a prompt is not producing what was wanted, when output varies run to run, when writing a prompt for a repeated task, when moving a prompt between models, or when someone describes what they want an AI to do and needs it written properly.
---

# Prompt optimizer

## Diagnose before rewriting

Bad output has a small number of causes, and the fix differs entirely by cause:

- **Underspecified** — the model is guessing at something you know. Most common by far.
- **Overspecified** — so many constraints that they conflict, and the model satisfies some
  arbitrarily.
- **Wrong shape** — asking for a paragraph when you want a table, or a decision when you want
  options.
- **No success criterion** — nothing in the prompt says what good looks like, so quality varies with
  nothing.
- **Buried instruction** — the actual task is in the middle of context and gets weighted like
  context.
- **Genuinely hard** — the task needs information the model does not have, and no prompt fixes that.
  Say so rather than iterating.

Read the actual bad output before rewriting. The failure mode names the cause.

## What reliably helps

- **Say what to do, not what to avoid.** Negative instructions are weaker than positive ones and
  often summon the thing named.
- **Give the shape of the output** — the sections, the length, the format. If format matters, show
  an example rather than describing it.
- **Provide one worked example** where the task is judgment-heavy. Examples carry more instruction
  per token than description does, and one good one beats three mediocre.
- **State the audience and purpose.** "For a technical reader deciding whether to adopt this" changes
  the output more than most adjectives.
- **Ask for reasoning before the answer** on analytical tasks — order matters, since a conclusion
  stated first is defended rather than derived.
- **Give an out.** Tell it what to do when the input is insufficient, or it will invent something.

## What does not help

Politeness, threats, incentives, insisting on importance, and stacked superlatives. These consume
tokens and change little. So does repeating an instruction in three phrasings — it usually signals
the instruction is unclear rather than reinforcing it.

## Structure

Put the task first, context second, and any output format last where it will be closest to
generation. Long context between instruction and output is where instructions get lost.

For repeated prompts, separate the fixed instruction from the variable input explicitly, so the
model can tell which is which.

## Testing

A prompt is not done because one run looked good. Run it three to five times on the same input and
look at the variance — that is the actual quality. Then run it on the awkward inputs: empty, far too
long, ambiguous, adversarial.

Fix the worst case, not the average. The average is what you see in testing; the worst case is what
your users see.

## Producing variations

When a prompt matters enough to optimize, produce genuinely different versions rather than variants
of one phrasing:

- **Terse** — instruction only, minimal framing. Often outperforms, and it is cheapest.
- **Structured** — explicit sections, numbered constraints, defined output shape.
- **Exemplar-led** — one worked example carrying most of the instruction.
- **Role-framed** — audience and stance set before the task.

Test all four on the same inputs. Which wins is genuinely hard to predict, and the intuition that a
longer prompt is better is wrong about as often as it is right.

## Scoring output

Judge against criteria written before seeing results, or you will rationalize whatever came back.
For most tasks: did it do the task, is it correct, is it the right shape and length, is it usable
without editing. Score each run rather than forming an overall impression — impressions are
dominated by the best run, and the worst run is what matters.

## Moving between models

Do not assume a prompt transfers. Models differ in how they weight system versus user instruction,
how they handle long context, and how they respond to formatting. Re-test on the target model, and
be especially suspicious of prompts tuned through many small iterations — those are often fitted to
one model's quirks.

## Never

- Rewrite a prompt before reading the failing outputs. You will fix the wrong thing.
- Change more than one thing between test runs.
- Judge a change on a single output. Sampling variance will fool you.
- Keep an instruction because it was already there. Every line has to earn its tokens.

View saved version →

---
name: release-and-deployment
description: Ships changes safely and often — pipelines, deployment strategies, feature flags, rollback, and database changes. Use this to design a deployment pipeline, reduce release risk, roll out a risky change gradually, plan a schema migration, or work out why releases are infrequent and frightening.
---

# Release and deployment

Release risk is dominated by batch size. Large infrequent releases are dangerous because many changes
land at once and nobody can tell which one broke it — so teams release less often, which makes each
release larger. The loop is the problem.

## Separate deploy from release

Deploying code and exposing behavior to users are different acts, and coupling them forces every
deployment to be a business decision.

Decouple with flags: deploy continuously, expose deliberately. This makes rollback a configuration
change rather than a redeployment, which is the difference between seconds and minutes at the worst
possible time.

Flags are inventory and rot. Give each an owner and a removal date; a codebase full of stale flags
has combinatorial states nobody has tested.

## The pipeline is the quality gate

Automate everything between commit and production, and let the pipeline reject. Manual steps get
skipped under pressure, which is exactly when they matter.

Order gates fast-to-slow so failure is cheap: lint and unit tests, then integration, then anything
requiring a deployed environment. A pipeline slow enough to be circumvented is worse than a fast one
with fewer checks, because it will be circumvented.

Build once and promote the same artifact through environments. Rebuilding per environment means the
thing you tested is not the thing you shipped.

## Roll out gradually

Expose to a small population first and watch real signals before widening. Canary or percentage
rollout turns a total failure into a contained one.

Define the abort condition **before** starting, with a threshold and a named decision-maker. Under
pressure, and with the change fresh, the instinct is always to wait a little longer and see.

## Database changes are the asymmetric risk

Code rolls back; data does not. Make schema changes backward-compatible and multi-step: add the new
structure, write to both, migrate, switch reads, then remove the old — with the application tolerant
of both shapes throughout.

Test the migration against production-scale data. A migration that is instant on a development
dataset can lock a large table for a length of time nobody modeled.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Tooling

Pipelines: GitHub Actions, GitLab CI, CircleCI, Buildkite, Jenkins, and similar.

Continuous delivery and progressive rollout: Argo CD, Flux, Spinnaker, and similar; feature flags
for decoupling deploy from release — LaunchDarkly, Unleash, Split, and similar.

Schema migrations: Flyway, Liquibase, Alembic, and similar. Whichever you use, the property that
matters is that migrations are versioned, ordered, and applied by the pipeline rather than by a
person with a database client.

## Never

- Couple deploying code to exposing behavior.
- Promote a different artifact than the one that was tested.
- Begin a rollout without a defined abort condition.
- Ship a schema change that requires the application and database to deploy simultaneously.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: skill-authoring
description: Writes and revises agent skills so they trigger at the right moments and give usable instruction when they do. Use this when creating a new skill, editing an existing one, diagnosing a skill that fires too often or never fires, or reviewing a set of skills for overlap. Also use before adding to a skill library, to check the capability is not already covered.
---

# Skill authoring

A skill is judged twice: on whether it loads at the right moment, and on whether it helps once
loaded. Most fail the first test.

## The description does the triggering

It is the only part read when deciding whether to load. Write it for that job:

- Lead with **what the skill does**, in one clause.
- Then **when to reach for it** — the situations, in the words someone would actually use, including
  the oblique ones ("why isn't this converting" as well as "CRO audit").
- Name the **edge cases that should still trigger it**, and where useful, what should *not*.

Vague descriptions produce two failures at once: the skill misses cases it should catch, and fires
on cases it cannot help.

## The body does the work

Write for someone competent who has not thought about this problem today. That means:

- **Method over exhortation.** "Be thorough" is noise. An ordered procedure is instruction.
- **State the failure behind each rule.** A rule with no failure attached gets optimized away by the
  next reader.
- **Be specific enough to be wrong.** Guidance too hedged to contradict is too vague to follow.
- **Put long material in `references/`** and say when to read it. The body should fit in working
  memory.

## Overlap is the silent killer

Two skills whose descriptions both match a request means neither reliably wins. Before adding one,
check what already covers the ground. Prefer extending an existing skill, or consolidating the
family into one skill with references, over adding a near-neighbor.

## Mechanics

- `name` must be lowercase-hyphenated and equal the directory name, or the skill will not load.
- One skill, one directory, `SKILL.md` at its root; supporting material in `references/` and
  `scripts/`.

## Verify before shipping

Write three requests that should trigger it and two that should not, and check the description
actually discriminates. If a near-miss request would pull it in, tighten the description.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Never

- Ship a skill whose description does not say when to use it. A skill that never triggers is dead weight.
- Write a skill that restates what the model already does well without prompting.
- Let two skills claim the same trigger. Move the boundary or merge them.
- Ship without running the skill against the case that motivated writing it.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: solution-architecture
description: Designs system structure and makes architectural decisions defensible — boundaries, coupling, trade-offs, and recording why. Use this to design a new system or major component, choose between architectural options, review an existing design, decide where a boundary belongs, or document an architectural decision so it survives the people who made it.
---

# Solution architecture

Architecture is the set of decisions that are expensive to reverse. Everything cheap to change later
is design, and does not need this level of ceremony.

## Start from what constrains, not from what appeals

Architecture is driven by quality attributes, not by features. Establish the ones that actually bind
before drawing anything: expected load and its shape, latency the user notices, availability the
business will fund, data residency and retention obligations, the rate of change the team needs to
sustain, and the size and skills of the team who will operate it.

Vague attributes produce vague architecture. "Scalable" is not a requirement; "20,000 concurrent
sessions with p99 under 300ms" is a constraint that eliminates options.

## Boundaries are the whole game

Draw boundaries where change is independent and where data has a single owner. A boundary in the
right place absorbs change; a boundary in the wrong place turns every feature into a negotiation
across three teams.

The reliable test: if a routine change requires coordinated deployment across two components, the
boundary is wrong regardless of how clean the diagram looks.

Prefer coarse boundaries until you have evidence for finer ones. Distributed systems convert simple
in-process failures into network, partial-failure and consistency problems — a cost worth paying for
independent scaling or independent deployment, and not worth paying for tidiness.

## Trade-offs, stated

Every architecture sacrifices something. The failure is not choosing badly; it is choosing without
naming what was given up, so nobody later understands why the constraint exists.

Present options with their costs: what each makes easy, what each makes hard, what it costs to
operate, and what it would take to reverse. Two credible options and an honest comparison beat one
recommendation.

## Record decisions

Write down the decision, the context at the time, the options considered, and the consequences
accepted. Architecture rots because the reasoning evaporates while the structure remains, and the
next team reads a constraint as an accident.

Keep records short and immutable — supersede rather than edit, so the history of thinking survives.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Never

- Design against quality attributes nobody has quantified.
- Split a system into services to make the diagram tidy.
- Present a single option as though no trade-off was made.
- Leave an expensive-to-reverse decision undocumented.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: solution-exploration
description: Explores the problem and the range of possible approaches before any code is written — clarifying what is actually being asked, surfacing options with their tradeoffs, and converging on one. Use this at the start of any feature, component, or behavior change, when a request is ambiguous, when the first idea is the only idea on the table, or when a design decision needs pressure-testing before commitment.
---

# Solution exploration

The most expensive bugs are decisions, not defects. This runs before implementation, not instead of
it.

## Establish what is actually wanted

The stated request is a proposed solution wearing the clothes of a requirement. Get underneath it:

- What outcome does the person want? What breaks today without it?
- Who else touches this, and what do they assume about it now?
- What is explicitly **not** being asked for?
- How will we know it worked — the observable difference.

If the answers conflict, stop and resolve that first. Building the average of two requirements
satisfies neither.

## Generate genuinely different options

Two variations of the same idea are one option. Force real range:

- The smallest thing that could work.
- The version that assumes this doubles in scope next quarter.
- The version that requires no new moving parts.
- Buy, borrow, or do nothing.

For each: what it costs, what it forecloses, and what has to be true for it to be right.

## Converge

Recommend one and say why the others lost. A comparison that ends without a recommendation has
moved the work, not done it.

Name the assumption the recommendation rests on most heavily — that is where the plan will break if
it breaks.

## Never

- Present options you would not accept as padding around the one you want.
- Skip this because the task "is simple." Simple tasks take five minutes here.
- Let a preference stand in for a reason.

View saved version →

---
name: systematic-debugging
description: Finds the root cause of a bug, test failure, or unexpected behavior before proposing any fix. Use this whenever something is broken and the cause is not yet proven — a failing test, a production error, intermittent behavior, or a symptom that appeared after a change. Also use when a fix has been attempted and did not work, or when the same bug keeps coming back.
---

# Systematic debugging

## The rule

**No fix before the cause is proven.** A change that makes a symptom disappear without an
explanation has not fixed anything — it has moved the failure somewhere you are not looking.

## Method

1. **Reproduce it deterministically.** If you cannot make it happen on demand, you cannot know when
   it is fixed. Intermittent means you have not found the variable yet — order, timing, state,
   environment, data.
2. **Narrow the blast radius.** Bisect: which commit, which input, which branch, which layer. Halve
   the search space with each step rather than reading everything.
3. **State a hypothesis that can be wrong.** "The cache returns stale rows after a write" is a
   hypothesis. "Something is wrong with caching" is not.
4. **Test the hypothesis directly** — a log line, a breakpoint, a probe. Prove it, do not infer it.
5. **Explain the whole symptom.** If your cause explains the error but not why it started Tuesday,
   you have found *a* bug, not *the* bug.
6. **Fix, then verify by reverting.** Put the bug back and confirm the test fails again. This is the
   step people skip, and it is the one that proves causation rather than coincidence.

## Anti-patterns

- **Shotgun changes** — altering several things at once. Now you cannot attribute the fix.
- **"Probably a flake."** Not a diagnosis. A test that fails intermittently is reporting a real
  race, ordering dependency, or shared-state leak.
- **Fixing the symptom** — catching the exception, adding a retry, widening a timeout — without
  knowing what threw it.
- **Trusting the error message's location.** Where it surfaced is rarely where it originated.

## Never

- Close a bug without a reproduction that failed before the fix and passes after it.
- Deploy a change to production to find out whether it works. Reproduce somewhere you can observe first.
- Change the environment and the code in the same step.
- Leave a debugging aid in the code as the fix — a widened timeout, a disabled check, a swallowed exception.

## Return contract

State the reproduction, the proven cause, the fix, and the verification that the fix addresses that
cause specifically. Name anything you ruled out and how.

View saved version →

---
name: technical-debt-management
description: Makes technical debt visible and decidable — distinguishing real debt from mess, quantifying its cost, and arguing for remediation in business terms. Use this to assess and prioritize debt, decide whether to fix or live with something, justify remediation work to non-engineers, or plan a migration off a system nobody wants to touch.
---

# Technical debt management

Debt is a deliberate trade: taking on future cost to move faster now. Most of what gets called debt
is not that — it is mess, which was never a decision, or drift, where the world moved and the code
did not. The distinction matters because the arguments and remedies differ.

## Classify before prioritizing

- **Deliberate debt** — a known shortcut with a reason. Has a principal and interest. Legitimate.
- **Mess** — nobody chose it; it accumulated. No trade was made, so there is nothing to defend.
- **Drift** — the code was right for a context that has changed. Neither shortcut nor carelessness.
- **Not debt at all** — code someone dislikes, or would have written differently. Taste is not debt,
  and rewriting on taste is how remediation budgets get spent with nothing to show.

## Cost is a rate, not a total

Debt matters proportional to how often you pay it. Ugly code in a module nobody has touched in three
years costs nothing; a moderate awkwardness in the file every feature crosses costs continuously.

Measure by contact: change frequency, how long changes there take relative to elsewhere, how often
changes there cause incidents, and how many people avoid the area. Overlay change frequency on
complexity and the priorities become obvious and defensible — the expensive parts are where both are
high, which is rarely where intuition points.

## Argue in the language of the decision-maker

"The code is bad" loses to any feature request. What wins is the rate: this area consumes a
disproportionate share of delivery time, causes a disproportionate share of incidents, and the gap
widens.

Frame remediation as capacity recovery with a payback period — the same terms as
`finance:capital-allocation`, which is where any large migration will eventually be judged.

## Remediate incrementally

Large rewrites fail at a well-documented rate: they take longer than estimated, deliver no value
until the end, and are canceled halfway leaving two systems. Prefer strangling the old system
gradually behind a stable interface, so value lands continuously and the work can stop at any point
without leaving a mess.

Improve opportunistically where you are already working — the code you are touching anyway is the
cheapest code to improve, and it is by definition the code that is being touched.

## Sources

`references/sources.md` in this skill lists the outside authorities that settle the questions
here — what each one is authoritative for, and what you may do with it. Check them before
answering on anything they cover, and cite what you used. Most are free to read and not free
to reproduce; the use note on each is binding.

## Never

- Present debt as a quality argument to someone accountable for delivery dates.
- Prioritize by how bad code looks rather than how often it is paid for.
- Start a rewrite with no value delivered until completion.
- Classify taste as debt.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: test-driven-development
description: Drives implementation by writing a failing test first, then the smallest code that passes it. Use this before writing implementation code for any feature or bugfix, when a bug needs a regression test, when existing code is hard to change safely, or when someone asks whether a change is covered. Also use to decide what is worth testing and what is not.
---

# Test-driven development

## The loop

1. **Red** — write one test that fails for the right reason. Run it. A test that passes immediately
   is testing nothing; a test that errors instead of failing is testing the wrong thing.
2. **Green** — the smallest change that makes it pass. Ugly is fine here.
3. **Refactor** — clean up with the test green. If it goes red, you changed behavior, not structure.

Never skip step 1. Writing the test after the code produces a test shaped to the implementation,
which is the one shape that cannot catch the implementation being wrong.

## What to test

Test behavior at the boundary a caller actually depends on. For each unit ask: if this broke
silently, who notices and how? If the answer is nobody, delete the code rather than test it.

- **Test**: branching logic, boundary conditions, error paths, anything with a past bug, contracts
  between modules.
- **Do not test**: getters, framework behavior, private helpers reachable only through a public path
  already covered, exact wording of log lines.

## Bugs

Every bug gets a failing test *before* the fix, reproducing it at the smallest scope that shows it.
That test is the proof the bug existed and the guard that it stays fixed. A fix without one is a
claim.

## Rules

- One behavior per test. A test asserting five things tells you almost nothing when it fails.
- The test name states the behavior, not the method: `rejects_expired_token`, not `test_auth`.
- Never weaken an assertion to get green. If a test is inconvenient, the design is telling you
  something.
- Never mock what you own — mock the network and the clock, not your own modules. Mocking your own
  code tests the mock.

## Never

- Write the test after the code and call it test-driven. You will test what you built rather than what was required.
- Skip watching the test fail. A test that has never failed proves nothing.
- Delete or skip a failing test to unblock a release. Fix it, or revert what broke it.
- Treat a coverage number as the goal. It counts lines executed, not behavior pinned down.

## Return contract

Report the tests added, what each pins down, what is deliberately untested and why, and the actual
command you ran with its output. "Tests pass" without the command output is not a result.