菜单
Places every error detection at the earliest stage of the pipeline that is technically capable of catching it. Use when designing or auditing a CI/CD pipeline, choosing tooling, deciding where a check belongs, or asking "could this have been caught earlier?"
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | defect-shift-left |
| description | Places every error detection at the earliest stage of the pipeline that is technically capable of catching it. Use when designing or auditing a CI/CD pipeline, choosing tooling, deciding where a check belongs, or asking "could this have been caught earlier?" |
Pipeline stages have a strict order. Every defect has an earliest stage at which it can be caught. Catching it later is always a regression.
Core Directives
- Prevent over detect. Make invalid states unrepresentable before adding a check.
- Earliest possible stage is mandatory. If a check can run at stage N, running it at N+1 is a regression.
- Replace same-scope duplicates. When shifting a check earlier, remove any later check that covers the same scope. Keep a later backstop only when it covers a broader or less-bypassable scope.
- Fail loud at the origin. Errors must surface where they originated.
Improvement Trio
defect-shift-left: move defect detection earlier.push-out: move recurring operational work outward.bring-down: move bespoke code down into reusable capability.
| Stage | Rank | Phase | What runs here |
|---|---|---|---|
| 0 | 0 | Language | Type system, syntax, language semantics |
| 1 | 1 | Design | Spec, ADR, threat model, schema |
| 2 | 2 | Authoring | LSP, in-editor lint, formatter |
| 3 | 3 | Pre-commit | Format, fast lint, secret scan, commit-msg hook |
| 4 | 4 | Compile | Compiler, type-checker, codegen |
| 5 | 5 | Build / Static analysis | Full lint, depcheck, SAST, license, CVE, bundle, IaC, fitness functions |
| 6 | 6 | Unit test | Local test runner, property tests |
| 7 | 7 | Integration / Contract | CI suite, contract tests, container builds |
| 8a | 8 | Pre-deploy static | Migration dry-run, config-vs-env, capacity, IAM diff (deploy abortable) |
| 8b | 9 | Deploy execution | Smoke, health probes, slot readiness (rollback on failure) |
| 9 | 10 | Canary / Staging | Partial traffic, real env, perf regression |
| 10 | 11 | Production runtime | Live traffic, monitoring |
| 11 | 12 | Post-incident | Forensics, RCA |
Cost grows roughly geometrically with rank. The ladder is monotonic — later
detection is never neutral. Use Rank for distance math; stage labels like
8a and 8b are names, not numbers.
Stages 8a and 8b are split because some defects only become detectable when target-environment state is available; pre-deploy can abort cheaply, deploy execution requires rollback.
Before adding any check at Stage ≥1, ask: can a type or schema make this defect unrepresentable? If yes, the check belongs at Stage 0.
| Technique | Eliminates |
|---|---|
| Strong / branded types | Type confusion, semantic mixing |
| Sum types + exhaustive matching | Missing case, silent fallthrough |
| Option / Result types | Null deref, silent failure |
| Refinement types | Range, off-by-one |
| Linear / affine types | Use-after-free, double-close |
| Schema-as-code | Config drift, contract mismatch |
| Const / immutable default | Accidental mutation, race |
Strict compiler flags (strict, noUncheckedIndexedAccess, strictNullChecks, --strict) | Whole defect classes without writing new types — flip a flag, the compiler enumerates the gaps |
| Defect class | Stage | Mechanism (fallback) |
|---|---|---|
| Type mismatch, null deref, semantic-type mixing | 0 | Type system |
| Missing case handling | 0 | Exhaustive sum types |
| Off-by-one / range | 0 | Refinement types (else 6: property test) |
| Use-after-free, race | 0 | Linear / borrow types (else 5: static analysis) |
| Generated code drift from schema | 0 | Codegen types (else 5: codegen drift check) |
| Contract / schema absent or ambiguous | 1 | Shared schema / spec |
| Authorization model gap | 1 | Threat model (else 7: security test) |
| Style, formatting, unused code, API misuse | 2 | LSP / editor (else 5: lint) |
| Banned API / unsafe pattern | 2 | LSP rule (else 5: lint) |
| Forbidden architectural dependency | 2 | Editor import rule (else 5: depcheck / lint) |
| Committed config violates schema | 2 | Editor schema hint (else 5: schema validation) |
| Secret in source | 3 | Pre-commit scanner (else 5: SAST) |
| Symbol resolution / missing import | 4 | Compiler |
| CVE in dependency | 5 | SCA audit |
| License incompatibility | 5 | License audit |
| Bundle / artifact regression | 5 | Bundle validator |
| Logic error in pure function | 6 | Unit test |
| Property violation across input space | 6 | Property test |
| Integration boundary mismatch | 7 | Contract test |
| Container / build reproducibility | 7 | CI image build |
| Performance regression (micro) | 7 | Benchmark (else 9: load test) |
| Migration vs current schema | 8a | Dry-run against prod DB |
| Irreversible migration | 8a | Reversibility check |
| Cross-service version skew | 8a | Version-matrix gate |
| Backwards-incompatible API change | 8a | Contract diff vs deployed |
| Missing / expired secret in target env | 8a | Secret-store presence check |
| Undefined feature flag in target | 8a | Flag-store consistency |
| Target-env config violates schema | 8a | Pre-deploy config / env validation |
| Capacity / quota exceeded | 8a | Resource projection |
| IAM permission expansion | 8a | IAM diff |
| Cost / budget breach | 8a | Cost projection |
| Missing rollback artifact | 8a | Registry probe |
| Compliance approval missing | 8a | Policy gate |
| Artifact crashes on boot | 8b | Startup smoke |
| Health probe never passes | 8b | Orchestrator readiness gate |
| Target env unreachable dependency | 8b | Boot connectivity check |
| Resource exhaustion under load | 9 | Load test |
| Real-world latency / SLO breach | 10 | Production monitoring |
| Situation | Action |
|---|---|
| Proposed = earliest possible | Proceed |
| Proposed > earliest, earlier feasible now | Reject — implement at the earlier stage |
| Proposed > earliest, earlier requires effort | Document gap as technical debt; schedule shift |
| No check; defects only found in production | Critical — work backward from Stage 10 |
| Check requires target-env state | Stage 8a is earliest — do not push to Stage 10 |
| Check exists but does not block | Promote to blocking gate or remove as theatre |
| Later check covers same scope as earlier check | Remove later duplicate after proof |
| Later check covers broader / unbypassable scope | Keep as backstop; record distinct scope |
Emit one coder-facing row per gap:
| Defect class | Current stage | Earliest stage | Stage distance | Mechanism | Decision | Owner/check | Verification | Next action |
|---|
If a gap remains, state: "Detection Gap: defect class catchable at Stage [X], currently at Stage [Y]. Mechanism: [...]."
| Pattern | Actual / earliest |
|---|---|
| Runtime check for type errors | Stage 10 / Stage 0 |
| CI formatting check with no editor support | Stage 5 / Stage 2 |
| Linter only in CI | Stage 5 / Stage 2 + Stage 5 |
| Code review as primary defect filter | Manual / Stage 2–5 |
| Production monitor for known-bad input | Stage 10 / Stage 0 |
| Compile errors hidden behind dynamic types | Stage 6+ / Stage 0 |
| Manual deployment checklist | Manual / Stage 5 or 8a |
| Documentation as the contract | Stage 7+ / Stage 1 |
| Deploy-and-pray monitoring | Stage 10 / Stage 8a |
| Migration applied without dry-run | Stage 8b–10 / Stage 8a |
| Secrets / config validated only at runtime | Stage 10 / Stage 8a |
| Manual rollback on deploy failure | Stage 10 / Stage 8b |
| No canary, full traffic on new artifact | Stage 10 carries full blast radius |
| Retry as error handling | Hides Stage 10 indefinitely |
| Catch-and-log silent failure | Propagates past origin |
| Warnings nobody reads | Detection without action |
Recurring moves that shift a defect class from a later stage to an earlier one. Recognise them; apply them deliberately.
| Shifts | Type errors, null deref, registry-shape drift, silent undefined from bracket access |
| From | Stage 6+ (unit test) or Stage 10 (production) |
| To | Stage 0 (type system) |
Convert source to a language with a checking compiler (JS → TS, Python → typed
Python under mypy/pyright, Ruby → RBS/Sorbet). Then progressively enable the
strictest flags — strict, noUncheckedIndexedAccess, strictNullChecks — and
retire every @ts-nocheck / # type: ignore escape hatch. Each flag flip is
its own shift: the compiler enumerates the defects, you fix them in batches.
The shift completes only when the strict typecheck is a blocking gate at both pre-commit (fast feedback on staged files) and CI (full-repo backstop). A typecheck nobody runs is theatre — see §6.4.
| Shifts | Forbidden imports, layering violations, banned API usage, accidental cross-module coupling |
| From | Stage 1 (design doc) or Stage 7+ (code review) |
| To | Stage 2 (editor rule) + Stage 5 (blocking static analysis) |
Architectural rules expressed in prose are advice; rules expressed in lint
config are enforcement. eslint-plugin-boundaries,
import/no-restricted-paths, dependency-cruiser, ArchUnit (JVM), Pyright
import rules — all turn an ADR sentence into editor feedback and a build
failure.
The recipe: encode each architectural decision as a rule that fails the build when violated. The ADR document remains as rationale; the lint config is the enforcement.
For the encoding pattern see architecture-as-code, with concrete
implementations in architecture-as-code-javascript or
architecture-as-code-python. For first principles see
architecture-guidelines; for the spatial rationale this enforces, see
geometric-architecture.
| Shifts | Config drift, API contract mismatch, malformed input, doc-vs-reality skew |
| From | Stage 6+ (hand-rolled if-chain validators) or Stage 10 (runtime parse errors, prose-as-contract) |
| To | Stage 0 (codegen), Stage 2 (editor), Stage 5 (build), Stage 8a (deploy) — one artifact, multiple rungs |
Schemas are the highest-leverage shift in this catalogue because the same artifact powers checks at every stage that can read it:
json-schema-to-typescript; OpenAPI → server / client stubs; Protobuf → typed
clients; XSD → C# / Java classes.$schema in JSON, xsi:schemaLocation in XML, YAML
language server hints).ajv,
xmllint, spectral for OpenAPI, buf lint for Protobuf).zod, typebox, io-ts,
valibot) make the schema the single source: static type plus runtime
validator generated from one declaration. Use at every external input
boundary (HTTP body, env vars, message payload).Catalogue: JSON Schema (configs, package.json), OpenAPI (HTTP), gRPC /
Protobuf (service-to-service), GraphQL SDL, AsyncAPI (events), Avro (streaming),
XSD (XML / SOAP).
The win is not "we validate" — it is "validation comes from a single artifact that fans out to every appropriate stage." Two hand-written sources checking the same shape are the same-scope duplication §Directive 3 forbids; one schema is the antidote.
| Shifts | The check itself, from advisory to enforced |
| From | Stage where the check exists but does not block |
| To | Same stage, now a gate |
The most common shift-left failure is having the right check at the right stage
and not making it block. A typecheck run as a manual npm run command has zero
shift-left value relative to no typecheck at all. Audit:
error or warn?§Directive 3 allows later backstops when two layers run the same check on different scopes:
--no-verify.Both are warranted: different blast radii (single commit vs. branch), different bypass costs. Layering pays when the earlier layer is faster and bypassable — the later layer is the un-bypassable backstop, not a duplicate.
Use this only when the user asks for tooling recommendations or implementation options. A plain shift-left audit stops at the missing category.
| Stage | Tool category to look for |
|---|---|
| 0 | Type system / compiler strictness flags / schema-as-code library |
| 1 | ADR template, schema registry, threat-model artifact |
| 2 | LSP, editor lint integration, formatter-on-save |
| 3 | Hook runner, secret scanner, commit-message linter |
| 4 | Compiler / type-checker invoked in build |
| 5 | Linter, dependency auditor, SAST, license checker, IaC scanner |
| 6 | Unit test runner, property-test library, coverage gate |
| 7 | Integration / contract test harness, container build verifier |
| 8a | Migration dry-run, config validator, IAM diff, cost projector |
| 8b | Smoke-test runner, health-probe spec, orchestrator readiness gate |
| 9 | Canary controller, load generator, perf-regression gate |
| 10 | Runtime monitoring, error tracker, SLO alerting |
| 11 | Incident-record system, RCA template |
Produce one row per gap:
| Stage | Defect class at risk | Detected stack signal | Candidate tool category | Specific options (cited) | Effort |
|---|
Do not propose a tool without naming the stage it staffs and the defect class it catches. A tool that does not map to a rung on §1 has no place in the output.
architecture-as-code — the codified-architecture pattern this skill names in §6.2.architecture-guidelines — first-principles rules whose violations this skill places on the ladder.ci-cd-reliability-architecture — pipeline rules that staff Stages 5–10.push-out — move recurring operational work out of human/manual execution into durable systems.bring-down — move bespoke or duplicated code down into reusable capability.continuous-improvement — how to promote a recurring escaped-defect into a permanent gate (Directive 1).Runs a lightweight change preflight, then routes non-trivial design, refactor, and audit work through only the needed requirements and A.L.C.H.E.M.Y. skills. Explicitly trigger with `/alchemy`, `$alchemy`, or natural phrases such as "do some alchemy", "run alchemy on this", "use alchemy", or "give this an alchemy pass". Use for architecture, complexity, enforcement, shift-left, optimization, modules, vertical slices, abstractions, cross-boundary refactors, consolidation, and over-engineering audits. Explicit invocation on a local bug fix, content or CSS edit, dependency bump, or trivial rename returns a cheap `SKIP` or `DIRECT` dispatch instead of loading every gate. Defines no new domain rules; routes to core sibling skills and task-matched companion skills.
Protocol for updating skills based on user feedback and root-cause analysis to prevent recurring mistakes. Use this skill when deciding HOW and WHEN to evaluate or update other agent skills.
Determines whether graph-structured requirements are ready for architecture, development, and verification, then derives the smallest coherent build-preparation package without inventing requirement meaning. Use when producing capability maps, epics or workstreams, implementation slices, dependency sequencing, contract candidates, domain-model seeds, cross-cutting constraints, acceptance-test references, ADR seeds, technical questions, or explicit ready/partly-ready/not-ready decisions. Do not use for initial discovery or requirement graph normalization.
Grounds proposed requirements in a real actor-bound problem, explicit scope, authoritative sources, evidence, assumptions, priority, and validation confidence. Use when defining or sharpening a problem, extracting obligations or stakeholder needs, separating facts from interpretations and hypotheses, writing solution-free requirement candidates, deciding what belongs in scope, reverse-engineering provisional requirements from existing code, tests, schemas, configuration, public interfaces, documentation, or history, or determining whether requirements are ready for dependency modeling. Do not use for graph construction or implementation planning except to prepare their inputs.
Structures validated requirements into an atomic, traceable, typed dependency graph and derives a trustworthy dependency order. Use when normalizing requirement wording, preserving stable IDs, splitting or merging requirements, modeling dependencies and constraints, detecting duplicates, conflicts, cycles, orphans, stale references, or missing verification, refining requirement-scope boundaries, or producing a graph package. Do not use for initial problem discovery or implementation planning.
Maintains bidirectional traceability between canonical requirements and implementation, verification, decision, and operational evidence. Use when planning, implementing, reviewing, or closing work that must prove which requirement authorized a change, where it is implemented, which executed evidence verifies it, what remains unmapped, or whether references have gone stale. Do not use to invent requirement meaning, normalize the requirement graph, or decide implementation readiness.