Architecture & Engineering — Skills

System Architecture Specification

Turns a scope and its measured requirements into an architecture someone can build from — with every component traced to a requirement and every decision carrying the alternatives it beat.

Deliverable

One Markdown document, architecture-specification.md, in the structure set out under Output below. It takes the output of Non-Functional Requirements Definition and feeds API Contract Design and Data Model & Migration Plan.

Required inputs

The scope — the capabilities the system must provide, as a list. A scope definition is the expected form; any list of separately describable capabilities will do.
The non-functional requirements — the measured constraints the design must satisfy, each with its metric and the condition it holds under.
A named decision owner — the person who can accept an architectural decision and the alternatives it rejects. Without one, the decisions section is a suggestion.

If the scope is absent, stop and report it. Never derive the scope from an existing system: a running system records what was built and what was abandoned halfway, and neither is a requirement.

Optional inputs

Access to the existing system: repositories, schemas, configuration, operational documentation
The operating environment and its constraints: isolation rules, regions, network boundaries, hosting model
The conventions the team already follows and the systems it already runs
Integration points outside the boundary, and who owns each of them
Compliance, residency or retention obligations that apply to the data
Earlier architecture documents for the same system, and what has changed since

Every optional input that is absent becomes an entry under Open questions. It never becomes a guess. Where the operating environment was not supplied, the deployment shape is described in runtime units and its placement is recorded unknown.

Execution

1 — Fix the boundary. Name the system, what is inside it and what is outside. List every external actor — people, systems, scheduled processes — and what each one wants from the system. Anything that cannot be placed on one side is a boundary question, recorded as one rather than decided quietly.

2 — Derive the components from the capabilities. For each capability in the scope, name the component that owns it. Give each component one sentence of what it owns and one of what it explicitly does not. Two components that own the same thing are one component with an unresolved name; a component that owns nothing is deleted.

3 — Define the interfaces. For every pair of components that must communicate: the direction, what is exchanged, whether the call is synchronous or asynchronous, and what the caller does when the far side is unavailable. Interfaces are named and bounded here; they are specified field by field by API Contract Design.

4 — Name the data that crosses each boundary. For each interface and each external actor: what data crosses, its classification, who owns it, and how long it may be kept. Data whose classification was not supplied is recorded unknown and raised as a question; it is never assigned a classification by this skill.

5 — Shape the deployment. The runtime units, how many of each, what state each holds, how each is reached, and where the boundaries of failure lie. Build this from the stated environment only. Where none was stated, describe the units and their relationships and mark their placement unknown.

6 — Record the decisions. For every choice that is expensive to reverse: what was decided, what forced it, the alternatives considered and why each was rejected, and the condition that would reverse it. A decision with no rejected alternative was not a decision; it was the first idea, and it is recorded as one.

7 — Trace and prune. Every component must trace to a capability or to a non-functional requirement. A component that traces to nothing is flagged in the traceability section, not kept on the diagram. Every capability must reach at least one component; a capability that reaches none is a gap and is raised as blocking.

Output

architecture-specification.md, in this order:

1. Input and date — which scope and which requirement set this specification is built from, who supplied each, and when
2. System context — the system, its external actors, and what each exchanges with it
3. Components — per component: name, what it owns, what it explicitly does not own, and what it traces to
4. Interfaces — per interface: the two sides, direction, what is exchanged, synchronous or asynchronous, and the behaviour when the far side is unavailable
5. Data across boundaries — per boundary: the data, its classification, its owner, and its retention
6. Deployment shape — runtime units, their multiplicity, the state each holds, how each is reached, and the failure boundaries
7. Architectural decisions — the decision, what forced it, the alternatives rejected and why, and what would reverse it
8. Traceability — component to requirement and requirement to component, with the unmatched entries on both sides listed
9. Open questions — the question, what it blocks, who can answer it

Validation

The specification is ready when all of these hold:

Every component in section 3 traces to a capability or a requirement in section 8, or is flagged there as tracing to nothing
Every capability in the input scope reaches at least one component
Every interface in section 4 states what the caller does when the far side is unavailable
Every decision in section 7 names at least one rejected alternative and the reason it was rejected
Every item in section 5 carries a classification or the literal unknown
Section 9 is either non-empty or states explicitly that nothing is outstanding

Fail the run if a component traces to nothing and is not flagged, or if a decision is recorded with no alternative considered.

Failure handling

No scope supplied — stop. Report that the specification has no capabilities to allocate, and that a component list assembled without them describes a preference rather than a system.
No non-functional requirements — produce sections 1 to 5 and 7 to 9, mark section 6 UNCONSTRAINED, and state that a deployment shape resting on no stated load, availability or latency requirement may not be used to size anything.
No access to the existing system — build sections 2 and 3 from the reported material alone, mark every element reported, and state plainly that nothing was verified against a running system.
Contradictory inputs — record both, name both sources, and raise the contradiction in section 9 as blocking. Do not resolve it by choosing.
Partial material — produce every section the material supports, mark the rest INCOMPLETE — pending <question>, and deliver. A specification honest about its gaps can be reviewed; a complete-looking one that filled them cannot.

Download .md

API Contract Design

Turns the interactions an interface must support into a contract a consumer can build against — and adds no field that nobody described.

Deliverable

One Markdown document, api-contract.md, in the structure set out under Output below. It takes the interfaces named in section 4 of architecture-specification.md and is the input to implementation and to the tests written against it.

Required inputs

The interactions the interface must support — what a consumer needs to do, stated as tasks. A list of endpoints taken from an existing system describes what was built, not what is needed.
The consumers — who or what will call the interface, and what each one is permitted to see and to change.

If either is absent, stop and report it. A contract written without its consumers is a schema, and a schema is agreed with nobody.

Optional inputs

The data model the interface exposes, and the constraints already enforced on it
The authentication and authorisation scheme in use across the surrounding systems
Existing contracts in the same system, and the conventions they follow
The expected call patterns: which operations are called together, which are called repeatedly
The error taxonomy the consumers already handle
Transport, encoding or protocol constraints stated by the requester

Where a convention was not supplied, the contract states the choice it made and records it as a decision to confirm, never as a house style it assumed. Where a limit or a bound was not supplied, the rule is written and the value is left unknown.

Execution

1 — List the interactions, not the endpoints. One line per thing a consumer needs to do, in the consumer's words, with the consumer named against it. Endpoints are derived from this list. A list derived from endpoints reproduces whatever exists, including its mistakes.

2 — Name the resources and their operations. Group the interactions into the things the interface exposes, then the operations on each. An operation that belongs to no resource means a resource is missing: name the missing one rather than attaching the operation to the nearest resource that will hold it.

3 — Specify requests and responses field by field. For every field: name, type, required or optional, what it means, and what constrains it. A field the requester did not describe is not added. A field that looks necessary but was not described is raised as a question, because the answer changes who owns the data.

4 — Write the error catalogue. Every error a consumer can receive: the condition that raises it, whether the consumer may retry, and what the consumer is expected to do. An operation whose error conditions cannot be listed is not yet understood; record it as such rather than shipping a single generic failure.

5 — Set authentication and authorisation per operation. For each operation: what the caller must prove, what right is required, and what happens when the right is absent. An operation with no stated rule is recorded authorisation unknown — required before implementation. It is never defaulted to open, and never defaulted to closed.

6 — Define the behaviour rules. Idempotency per operation: safe to repeat, or what the caller must supply to make repetition safe. Pagination: how a page is requested, what bounds it, and what happens when the underlying set changes mid-traversal. Ordering, concurrency and rate limits are written only where the requester stated them.

7 — Set versioning and deprecation. What counts as a breaking change in this contract, how a breaking change is signalled, how a consumer learns that a version is ending, and how long a version is supported. Where the support period was not supplied, write unknown and name who must set it.

Output

api-contract.md, in this order:

1. Input and date — which interactions and which consumers this contract serves, who supplied them, and when
2. Consumers — per consumer: what it calls the interface for, and what it is permitted to see and to change
3. Resources and operations — per resource: what it represents, its operations, and the interaction each operation serves
4. Request and response schemas — per operation: every field with its name, type, optionality, meaning and constraint
5. Error catalogue — per error: the condition that raises it, whether it is retryable, and what the consumer must do
6. Authentication and authorisation — per operation: what must be proven, what right is required, and what happens without it
7. Behaviour rules — idempotency, pagination, ordering, concurrency, and rate limits where they were stated
8. Versioning and deprecation — what counts as a breaking change, how it is signalled, and how a version ends
9. Open questions — the question, what it blocks, who can answer it

Validation

The contract is ready when all of these hold:

Every interaction in the input reaches exactly one operation in section 3
Every field in section 4 carries a type and states whether it is required
Every error in section 5 names the condition that raises it and whether a retry is permitted
Every operation in section 6 states a rule or carries the marker authorisation unknown
No limit, bound or support period appears that the requester did not supply
Section 9 is either non-empty or states explicitly that nothing is outstanding

Fail the run if a field appears that no input described, or if an operation is published with neither an authorisation rule nor the unknown marker.

Failure handling

No interactions supplied — stop. Report that there is nothing to contract, and that an interface designed from a data model alone serves the store rather than the caller.
No consumers named — produce sections 1 and 3 to 9, mark section 2 UNKNOWN CONSUMERS, and state that section 6 cannot be settled until someone names who calls this.
Only an existing implementation is available — describe what the implementation does, mark the whole document AS-BUILT, and list in section 9 every behaviour that appears deliberate but is unconfirmed. An as-built description is not an agreed contract.
Consumers want contradictory behaviour — record both positions, name both consumers, and raise the conflict in section 9 as blocking. Do not satisfy both by making the difference an optional field.
Partial material — specify the operations the material supports, mark the rest INCOMPLETE — pending <question>, and deliver.

Download .md

Data Model & Migration Plan

Produces the model the system should hold and the reversible route from the storage that exists today to that model.

Deliverable

One Markdown document, data-model-and-migration.md, in the structure set out under Output below. It carries two joined artifacts — the target model and the runbook that reaches it — because a model with no route to it cannot be scheduled.

Required inputs

The entities the system must hold — what is stored and what each thing means to the people who use it. Sections 3 and 5 of architecture-specification.md are the expected form.
The current storage reality — the structures that exist now, read from the system or described by someone who runs it.

If the current state is absent, stop and report it. A migration planned against an assumed starting point is a plan for a different system, and it stops at the first step that touches real data.

Optional inputs

Direct access to the live structures, their keys, constraints and indexes
Data volumes and growth, as stated by the owner of the system
The retention, residency and deletion obligations attached to each entity
The access patterns the model must serve: what is read, what is written, what is read together
The release process the migration steps must fit inside
The window in which the system may be unavailable, if there is one, as stated by its owner

An absent volume never becomes a duration. Where volumes were not supplied, each step states its cost in terms of what it touches — which structures, which rows, which readers — rather than how long it takes.

Execution

1 — Record the current state exactly. Every structure on the path being changed, with its fields, keys, constraints and indexes. Mark each one observed if it was read from the system, or reported if a person described it. A step planned against a reported structure carries that risk into production, and the step says so.

2 — Model the target. Entities, attributes with their types, keys, relationships with their cardinality, the constraints that must hold, and the retention each entity carries. Every attribute traces to something the system must do; an attribute that traces to nothing is flagged rather than carried forward because it already exists.

3 — Index for the stated access patterns. An index exists to serve a read someone described. Where no access patterns were supplied, record the keys and uniqueness constraints only and mark the index set pending access patterns. Never add an index for a query nobody named.

4 — Diff current against target. Per difference: what changes, whether it is additive, destructive or a rename in disguise, and whether the data that exists can satisfy the new constraint. A constraint that current data would violate is a backfill with a decision behind it, not a schema change.

5 — Order the steps so each one is reversible. Additive structures first, alongside the old. Then the backfill, then the switch of readers, then the switch of writers, then the removal of what is now unused — each as its own step. A step that cannot be reversed states that inside the step, names what makes it irreversible, and names who accepts it.

6 — Write the verification and the rollback for every step. Per step: the check that proves it did what it claims, expressed as a comparison over the data rather than as a figure, and the exact action that undoes it. A step with no verification is not a step; it is a hope with a number next to it.

7 — State the cutover strategy. Dual write, read shadowing, or a bounded window of unavailability — whichever the stated constraints allow — with what it requires and what it costs while it runs. Where the owner stated no window, the plan assumes none is available and says so in the open questions.

Output

data-model-and-migration.md, in this order:

1. Input and date — which entities and which current state this plan works from, who supplied them, and when
2. Current state — per structure: fields, keys, constraints, indexes, and observed or reported
3. Target model — per entity: attributes and types, keys, relationships, constraints, retention, and what it traces to
4. Indexes — per index: the entity, the fields, and the access pattern it serves
5. Difference — per change: additive, destructive or a rename, and whether existing data satisfies it
6. Migration steps — in order; per step: what it does, whether it is reversible, and who accepts it when it is not
7. Backfill — per backfill: what is filled, from which source, and what is done with the rows that source cannot fill
8. Verification and rollback — per step: the check that proves it, and the action that undoes it
9. Cutover — the strategy, what it requires, and the unavailability it needs if any
10. Open questions — the question, what it blocks, who can answer it

Validation

The plan is ready when all of these hold:

Every entity in the input appears in section 3, or is recorded there as deliberately outside the model
Every attribute in section 3 traces to something the system must do, or is flagged as tracing to nothing
Every step in section 6 has a verification and a rollback in section 8
Every irreversible step declares its irreversibility inside the step and names who accepts it
Every index in section 4 names the access pattern it serves, or the whole set is marked pending access patterns
No volume, duration or row count appears that the owner of the system did not supply

Fail the run if a step is irreversible without saying so, or if any step reaches section 6 with no verification.

Failure handling

No current state supplied — stop. Deliver the target model alone if that was asked for, and report that no route to it can be planned from an unknown starting point.
Current state reported but not observed — produce the full plan, mark section 2 reported, and state in section 10 that every step must be re-checked against the real structures before it runs.
No access patterns supplied — produce sections 1 to 3 and 5 to 10, mark section 4 pending access patterns, and state that indexing is unresolved rather than settled.
A step cannot be made reversible — keep it, state what makes it irreversible, name the data that could not be recovered, and mark it as requiring a named acceptance before it runs. Do not bury it inside a larger step.
Partial material — plan the steps the material supports, mark the rest INCOMPLETE — pending <question>, and deliver.

Download .md

Non-Functional Requirements Definition

Turns quality wishes into requirements that can be tested — and asks the requester for every number instead of supplying one.

Deliverable

One Markdown document, nfr-specification.md, in the structure set out under Output below. It is the input to System Architecture Specification, which cannot shape a deployment without it.

Required inputs

What the system is for — who uses it, what they use it for, and what breaks for them when it degrades.
The expected load, as stated by the requester — how many users, how often, and what the peak looks like. Stated by a person or measured from a system; never derived by this skill.
The operating constraints — where the system runs, what it must interoperate with, and the obligations it carries.

If the purpose is absent, stop and report it. If load or constraints are absent, produce the specification with every affected threshold marked unresolved and name who must supply it. A load figure invented here would be tested against, met, and still unrelated to the system.

Optional inputs

Measurements from the system as it runs now, or from the system it replaces
The obligations that apply: regulatory, contractual, accessibility, data residency
What the business attaches to degradation and to unavailability, in its own terms
The environments and instrumentation available for measuring each attribute
The users and their conditions: devices, networks, assistive technology, locale
The requirements set for an earlier version, and which of them actually held

An absent optional input never becomes a number. Where no measurement is available, the requirement names the metric, the observation point and the method, and leaves the threshold unresolved with the person who must set it.

Execution

1 — Take the wishes verbatim. Record every quality statement in the words it arrived in, with who said it and when. Fast, reliable and secure are recorded exactly as written. They are the input to this skill, not its output, and rewriting them at this stage loses the person behind them.

2 — Attach each wish to an attribute. Performance, availability, scalability, security, operability, accessibility, compliance. A wish that touches several is split into one wish per attribute so each can be measured separately. A wish that fits none is carried forward as unresolved rather than forced into the nearest heading.

3 — Name the metric before the number. For each attribute in play: what is measured, in what unit, and observed where — at the client, at the system boundary, or inside a component. A metric agreed before a threshold is argued over is an argument about the system. The reverse is an argument about the number.

4 — Ask the requester for the threshold. Every threshold comes from the person accountable for the outcome or from a measurement of a running system. A threshold that neither source supplies is recorded unresolved — required from <name>. This skill proposes no value, not a target, not a floor, and not a conservative placeholder.

5 — State the condition each requirement holds under. The load, the data volume, the environment, the concurrency, and the period over which the measurement is taken. A threshold with no stated condition is met trivially: at rest, with no data, by a single user, on the fastest network available.

6 — State the consequence of missing it. What happens to the user, what happens to the business, and what happens to the release. A requirement whose consequence is that nothing happens is a preference; it is recorded as one and removed from the set that gates a release, so the gating set stays credible.

7 — Check the set against itself. Requirements that cannot all hold at once — the cost of one against the responsiveness of another, the isolation of one against the operability of another — are recorded as a trade-off with the person who must resolve it. They are never averaged into a set that looks achievable.

Output

nfr-specification.md, in this order:

1. Input and date — the purpose, the stated load, the constraints, who supplied each, and when
2. Wishes as received — verbatim, with who said it and when
3. Requirements — per requirement: attribute, metric, unit, observation point, threshold or unresolved, condition, measurement method, consequence
4. Unresolved — per item: the metric, why no threshold exists, and the person who must set it
5. Preferences — wishes with no consequence, kept out of the gating set and recorded as preferences
6. Conflicts — requirements that cannot hold together, and the person who must resolve the trade-off
7. Measurement plan — per metric: how it is measured, where, how often, and by whom
8. Open questions — the question, what it blocks, who can answer it

Validation

The specification is ready when all of these hold:

Every wish in section 2 appears exactly once in section 3, 4 or 5
Every requirement in section 3 names a metric, an observation point and a measurement method
Every requirement in section 3 carries either a threshold with its source or the marker unresolved
Every requirement in section 3 states the condition it holds under and the consequence of missing it
No threshold appears whose source is neither an input nor a measurement
Section 4 names a person against every unresolved threshold

Fail the run if any threshold appears without a source, or if a wish has been converted into a number that no input supplied.

Failure handling

No stated purpose — stop. Report that quality attributes cannot be ordered without knowing what the system is for, and that every attribute looks essential in isolation.
No load figures — produce the full specification with every load-dependent threshold unresolved, name who must supply the figures, and state that nothing in the set can be tested until they exist.
A number is demanded and none exists — deliver the metric, the observation point, the method and the condition, and leave the threshold unresolved. Report that a threshold chosen here would be measured, met, and meaningless.
Contradictory wishes from different people — record both verbatim with both names, and raise the conflict in section 6 for a named person to resolve. Do not merge them into a middle value.
Partial material — specify the attributes the material supports, mark the rest INCOMPLETE — pending <question>, and deliver.

Download .md

Technical Debt Audit

Turns a codebase into a register of what it costs to keep — ordered by the work each item blocks, not by how it looks.

Deliverable

One Markdown document, technical-debt-register.md, in the structure set out under Output below. It feeds planning directly: the ordered register is a list of items that can be sequenced against other work.

Required inputs

Access to the codebase, or documentation that describes it — enough to locate an item in a file or a module rather than in an impression.
What the team intends to build next — the work the debt is measured against. Debt is only debt relative to a change someone wants to make.

Without the second, the output is a list of things somebody dislikes. Without either, stop and report it: an audit with no material and no direction produces opinions with headings on them.

Optional inputs

The change history: what is modified most, and what keeps being modified together
Incident and defect records, and the areas of the system they point at
Test coverage, and the parts of the system the tests do not reach
Build and release records, and where they fail or wait
The team's own account of what slows them down, attributed to the person who said it
Earlier audits of the same system, and what was done about their findings

An absent source narrows the audit; it never widens the guessing. An item with no observable cost is recorded with its cost unknown, never with a cost that merely sounds plausible.

Execution

1 — Bound the audit. State what was examined and what was not: which parts of the system, which records, which period of history. An audit that does not state its boundary is read as complete, and the areas nobody looked at are read as clean.

2 — Collect candidates from evidence, not from taste. Every candidate needs an observation behind it: a failure, a change that had to be repeated in several places, an area the tests do not reach, a workaround someone described. Code that is merely unfamiliar or unfashionable is not a candidate and does not enter the register.

3 — Locate each item exactly. The file or the module, and the boundary of the item inside it. An item located at the level of a whole layer cannot be scheduled, cannot be argued about, and cannot be verified as fixed. Where the location is genuinely diffuse, say so and name the boundary that contains it.

4 — State the cost now, in observable terms. What does this item make someone do today: the manual step before a release, the change repeated in several places, the failure that recurs, the review that takes a second person. Where no cost can be observed, write cost unknown rather than converting an impression into a figure.

5 — State the interest. What the item charges on nearby work: which changes it makes slower, which changes it makes risky, and which changes it prevents outright. This is the section that separates debt from an imperfection, and an item that charges nothing on anything belongs in the accepted list.

6 — Size the remediation and its risk. What the fix is, what it touches, what it would take in the team's own unit of sizing if they supplied one, and what could break while it is done — including the work that must pause around it. Where the team supplied no sizing, record unsized and name who can size it.

7 — Order by what is blocked, and mark what is accepted. Rank the register by the work each item blocks, taken from the intended work supplied as input, and name that work against each item. An item that blocks nothing and costs nothing is recorded accepted with the reason — neither scheduled nor deleted.

Output

technical-debt-register.md, in this order:

1. Input and date — what was examined, what was not, which intended work the register is measured against, and when
2. Register — per item: what it is, where it is, the evidence behind it, and its cost now
3. Interest — per item: the work it slows, the work it makes risky, and the work it prevents
4. Remediation — per item: the fix, what it touches, its size or unsized, and the risk of doing it
5. Order — the items ranked by the work they block, with that work named against each
6. Accepted — items that cost nothing and block nothing, each with the reason it is accepted
7. Unverified — items reported by a person and not confirmed against the system
8. Open questions — the question, what it blocks, who can answer it

Validation

The register is ready when all of these hold:

Every item in section 2 names a file or a module and the evidence behind it
Every item in section 2 carries an observable cost or the marker cost unknown
Every item in section 3 names at least one piece of work it affects, or moves to section 6
Every item in section 4 states the risk of the remediation, not only the remediation
Section 5 is ordered by blocked work, and names the blocked work against each item
No size, count or proportion appears that the team did not supply

Fail the run if an item appears with no evidence behind it, or if the register is ordered by anything other than the work each item blocks.

Failure handling

No access to the codebase — audit the documentation supplied, place every item in section 7 as unverified, and state that a register built from documentation records what was written down rather than what is there.
No statement of intended work — produce sections 1 to 4, 7 and 8, leave section 5 unordered, and report that without intended work every ordering is a matter of taste.
The team supplied no sizing — record every remediation unsized, name who must size it, and deliver the register without a size column rather than with an invented one.
A finding is disputed by the team — keep the item, record the evidence and the dispute side by side with both names, and raise it in section 8. Do not remove an observed finding because it is unwelcome.
Partial access — audit what was reachable, name in section 1 exactly what was not, and deliver. An audit of part of a system is useful when it says which part.

Download .md