Keystone

View saved version →

---
name: change-review
description: Project change review for a concrete diff, branch, PR, patch, migration, fix, implementation result, or project plan that needs a new evidence-backed readiness verdict, or when another Keystone skill needs the Review Gate evaluated.
---

# Change Review

## Core principle
Change Review is an independent, read-only attempt to disprove readiness.

Ask two questions at the same time:
1. **Spec axis:** does the work satisfy the stated requirements and acceptance criteria?
2. **Standards axis:** is it secure, correct, maintainable, tested, and safe to operate?

Do not assume changed lines are the blast radius. Trace callers, callees, contracts,
data flow, tests, runtime paths, and user impact before giving a verdict.

## Load when
Load when a concrete software project artifact needs review: a diff, branch, PR, patch,
migration, fix, implementation result, or project plan that must be assessed against
its specification and engineering standards.

Also load when another Keystone skill needs `../../references/gates/review.md` satisfied before shipping.

At entry, use the full Keystone path when there is an inspectable project artifact and
a readiness or blocker verdict is the outcome. Handle general critiques, prose review,
and standalone explanations directly. Explicit invocation selects the full Change Review behavior.

## Not for
Do not use Change Review for:
- fixing, refactoring, formatting, or rewriting code
- committing, merging, tagging, publishing, or shipping
- initial implementation planning before a reviewable artifact exists
- open-ended context-survey with no concrete artifact to assess
- debugging where the requested outcome is a fix

If asked to review and fix, review first, stop, and hand findings to `implementation`, `root-cause-analysis`,
`context-survey`, `shipping`, or a human only after explicit permission.

## Outcome contract
A complete review returns:
- verdict: **Block**, **Caution**, or **Looks good**
- findings ordered P0, P1, P2, P3, then Nitpicks
- evidence for every finding: file/line, behavior path, contract, test, log, or doc
- user impact and why the severity is justified
- remediation guidance without applying the fix
- tests that should be added or updated for affected behavior
- scope reviewed, validation run, limitations, and read-only confirmation

The review is incomplete if it only inspects the diff, only comments on style, or
cannot explain how the work behaves at runtime.

## Change Review passes
Perform multiple passes. New evidence from one pass expands later passes.
### Pass 0: scope and baseline
- Identify artifact reviewed: diff, branch, files, release candidate, or plan result.
- Read the user request, issue, spec, acceptance criteria, and claimed completion.
- Check repository status without modifying files.
- Record uncommitted work as context, not cleanup.

### Pass 1: spec compliance
- Compare implementation against explicit requirements and non-goals.
- Check edge cases, error states, and acceptance criteria.
- Separate spec misses from standards concerns.
- Treat a clean implementation of the wrong behavior as a finding.

### Pass 2: correctness and runtime paths
- Trace primary success and failure paths end to end.
- Follow changed functions into helpers, services, adapters, persistence, UI, jobs, and
  serializers.
- Validate inputs, outputs, invariants, state transitions, retries, ordering,
  concurrency assumptions, and error propagation.
- Look for nullability, off-by-one, time, encoding, pagination, caching, idempotency,
  cancellation, and partial-failure issues.

### Pass 3: regression and compatibility
- Identify callers, consumers, and workflows that rely on old behavior.
- Check public APIs, CLIs, schemas, migrations, persisted data, environment variables,
  feature flags, configuration defaults, and documentation.
- Consider rollback, downgrade, mixed-version, and incremental rollout risks.
- Search for tests or fixtures that encode

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: context-survey
description: Project context survey for repository reconnaissance or project decisions that require evidence from existing code, project documentation, or project-specific external sources before planning or changing the project.
---

# Context Survey

## Core principle
Context Survey is evidence gathering before action. Inspect available material first, preserve source quality, separate facts from assumptions, and stay read-only unless the user explicitly asks for a durable context-survey artifact.

## Load when
Load when a software or product project needs:

- repository reconnaissance or understanding as the requested project outcome;
- evidence from existing code, tests, configuration, history, or project documentation;
- project-specific external documentation, standards, issues, market examples, or APIs;
- synthesis or validation of project evidence before another Keystone phase.

## Entry fit

An explicit invocation selects the full Context Survey behavior.

A Keystone handoff selects the full skill for project-bound repository understanding or evidence needed for a project decision or change.

For automatic entry, the prompt's subject must be project-bound. Load the full skill when repository understanding or reconnaissance is the requested outcome, or when this evidence contract materially improves a project decision or change. The current directory alone does not establish project scope.

For automatic routing of standalone public search, general research, ordinary explanation, or summarization unrelated to a project, use the direct research/answering path and return the requested result without Keystone gates.

## Not for
- Implementing, refactoring, editing, or fixing code.
- Shaping product direction beyond evidence-backed options.
- Broad tooling risk audits; use `project-audit`.
- Root-cause repair of a failure; use `root-cause-analysis` after initial context.
- Guessing when evidence can be inspected.

## Outcome contract
Deliver a context-survey brief that states:
- question or decision being supported;
- sources inspected, with file paths, commands, URLs, or other citations;
- source-quality notes (primary vs secondary, current vs stale, authoritative vs anecdotal);
- findings separated from assumptions and unknowns;
- confidence level and why;
- recommended next module, or `none` if no Keystone handoff is warranted.

## Modes
- **Repository read:** inspect files, history, configs, tests, docs, and existing behavior. Prefer primary project evidence.
- **External context-survey:** compare outside documentation, standards, issues, market examples, or APIs. Cite URLs and note recency.
- **Synthesis:** combine several sources into a decision-ready summary with tradeoffs and confidence.
- **Discovery scout:** map a large unknown area without drawing strong conclusions until evidence is sampled.

## Process
1. Restate the context-survey question or requested repository reconnaissance outcome, and the downstream decision when applicable.
2. Inspect before asking: search/read the repo, docs, logs, or provided sources before requesting more context.
3. Prefer primary evidence: source code, tests, product docs, official docs, reproducible commands, direct user-provided material.
4. Track citations as you go. Every important claim should point to evidence or be labeled as an assumption.
5. Evaluate source quality: age, authority, completeness, bias, and whether evidence is direct or inferred.
6. Compare alternatives when relevant, including costs, risks, constraints, and implications of taking no action.
7. State unknowns explicitly. Do not fill gaps with confident-sounding speculation.
8. Recommend the smallest next step: `product-planning`, `root-cause-analysis`, `project-audit`, `task-creation`, `implementation`, `change-review`, or stop.

## Subagents and reasoning
Use read-only subagents when the search space is large or evidence can be gathered independently. Use lightweight analysis for n

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: implementation
description: Executable-software implementation in an identified software project for features, diagnosed fixes, migrations, integrations, and build or release automation. Select only when the requested change alters runtime, API, data, build, or release behavior and requires project-specific verification of integrated effects.
---

# Implementation

## Core principle

Implementation changes through evidence, not vibes: isolate first, specify the next observable behavior, prove the test can fail, make the smallest correct change, then refactor without changing behavior.

Implementation is the mutation module. It may edit scoped project artifacts after the isolation gate passes, but it does not decide that work is shipped. Completion means "implemented with proof and handed to a change-review/shipping checkpoint," not finalized.

## Load when

Use Implementation when a named software or digital-product initiative needs:

- a feature, screen, endpoint, command, migration, or integration implemented;
- a diagnosed fix applied;
- architecture, module boundaries, interfaces, or contracts changed;
- an approved plan from `task-creation` executed;
- independent implementation slices delegated when a subagent tool is available;
- supporting artifacts only within an already-active behavior-changing implementation: required project configuration, documentation, content, or scripts.

## Entry fit

An explicit invocation selects the full Implementation behavior.

A Keystone handoff selects the full skill when a project change needs this mutation-and-proof contract.

For automatic entry, load the full skill when the prompt's subject is project-bound, the requested change alters executable software behavior, **and** this mutation-and-proof contract materially improves the change. The current directory alone does not establish project scope.

For automatic routing of a mechanical single-file configuration edit, one-off script, or other standalone small mutation that does not need project-specific context or proof gates, use the direct editing path and verify the requested result proportionately.

## Not for

Do not use Implementation for:

- routing unclear work: use `context-survey`
- context-surveying unknowns without mutation: use `context-survey`
- shaping requirements or acceptance criteria: use `product-planning`
- decomposing large work before implementation: use `task-creation`
- diagnosing a failure whose cause is unknown: use `root-cause-analysis`
- reviewing completed changes: use `change-review`
- releasing, merging, publishing, or finalizing: use `shipping`

## Outcome contract

Before Implementation exits, it must be able to report:

- isolation was checked before the first mutation via `../../references/gates/isolation.md`
- the exact user scope and protected files were respected
- the intended behavior or refactor invariant is stated plainly
- tests, examples, or checks prove the change, or gaps are explicitly disclosed
- `../../references/gates/red.md` passed for behavior changes
- `../../references/gates/proof.md` passed before any success claim
- delegated work, if any, was verified by the parent before acceptance
- `../../references/gates/checkpoint.md` decided the next required event

Implementation must not claim work is done because code "looks right." Proof and an explicit change-review/shipping checkpoint are required before completion claims.

## Modes

### TDD feature implementation

Use when adding or changing observable behavior.

Contract:

- define one behavior slice at a time
- write or identify the smallest test/check that should fail before the change
- run it and confirm the failure is meaningful, not caused by setup noise
- implement the smallest code that makes it pass
- run the focused check again
- run relevant regression checks
- refactor only while checks stay green

Load and pass `../../references/gates/red.md` for the red signal or its explicit exception. Prefer checks that 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: product-planning
description: Software product planning for a concrete software or digital-product initiative whose behavior, UX, user-facing copy, technical direction, scope, or acceptance criteria must be shaped before implementation, or whose approved direction must become a specification.
---

# Product Planning

## Core principle
Product Planning is a specification algorithm: turn an unclear intent into exact behavior, constraints, tradeoffs, and acceptance criteria before anyone implements. It decides what should be true, not whether code is complete.

## Load when
Load when a concrete software or digital-product initiative needs:

- product behavior, business rules, scope, success criteria, or acceptance criteria shaped before implementation;
- UX/UI flows, states, accessibility behavior, or visual constraints decided;
- user-facing product copy shaped as part of a feature or product experience;
- technical direction, boundaries, APIs, data flow, or architecture tradeoffs decided;
- alternatives explored for a project decision;
- approved direction converted into a specification;
- context-survey evidence converted into an implementation-ready direction.

## Entry fit

An explicit invocation selects the full Product Planning behavior.

A Keystone handoff selects the full skill when a concrete software or digital-product initiative needs this specification contract.

For automatic entry, load the full skill when the prompt's subject identifies a concrete software or digital-product initiative **and** this specification contract materially improves the decision. The current directory alone does not establish project scope.

For automatic routing of ordinary brainstorming, standalone copywriting, rewriting, naming, or visual ideation unrelated to a concrete software or digital-product initiative, use the direct creative/answering path and return the requested result without Keystone gates.

## Not for
- Writing implementation code or changing runtime behavior; hand off to `implementation`.
- Diagnosing failures; use `root-cause-analysis`.
- Broad repository audit or release readiness; use `project-audit` or `shipping`.
- Inventing facts that should be context-surveyed first.
- Polishing completed work as shippable proof.

## Outcome contract
Deliver a shaped proposal that includes:
- goal, user/audience, and success criteria;
- product behavior and UX states, including happy, empty, loading/pending, error/failure, and edge/constraint states where relevant;
- copy or content direction when user-facing text matters;
- architecture and scope tradeoffs at the level needed for planning, not implementation;
- alternatives considered and why one direction is preferred;
- acceptance criteria and non-goals;
- recommended next module (`task-creation`, `implementation`, `change-review`, `context-survey`) or `none` if no Keystone handoff is warranted.

## Modes
- **Product planning:** specify the user job, trigger, actor permissions, core flow, business rules, constraints, success metrics, non-goals, and acceptance criteria.
- **UX/UI planning:** specify layout hierarchy, navigation, interaction model, responsiveness, accessibility, visual constraints, and the 5-state UX checklist: happy, empty, loading/pending, error/failure, edge/constraint.
- **Copy planning:** specify audience, message hierarchy, claims, tone, CTA, labels, empty/error text, and prohibited vague claims.
- **Technical planning:** specify boundary placement, API granularity, data flow, state ownership, dependency direction, persistence/integration seams, and architectural tradeoffs without writing code.
- **Alternative exploration:** present multiple viable directions before choosing or asking the user to choose.

## Process
1. Classify the request into one or more modes: product, UX/UI, copy, technical, or alternatives.
2. Identify the goal, primary user/audience, job-to-be-done, context of use, and success criteria.
3. Inspect existing product patterns, d

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: project-audit
description: Project health audit for a concrete software repository or product subsystem. Use when its tooling, CI, dependencies, configuration, tests, documentation, packaging, architecture, or agent instructions need a whole-system condition and risk assessment.
---

# Project Audit

## Core principle
Project Audit is a read-only, whole-project condition scan. It turns repository evidence into mechanical findings about system drift, fragility, and maintenance risk; it does not repair, refactor, update, or reconfigure anything by default.

Project Audit answers “what is the condition of this project or subsystem?” Change Review answers “is this specific change acceptable?” If the task centers on a PR/diff/patch, use `change-review`; if it centers on repo-wide readiness, drift, tooling, docs, tests, releases, or operational condition, use `project-audit`.

## Load when
Load when the user asks for a whole-system condition scan of a concrete software repository or product subsystem: project health, release readiness, tooling/CI drift, dependency/config condition, maintenance risk, architecture smells, docs-vs-reality, test health, packaging, or instruction drift.

At entry, use the full Keystone path when repository or subsystem evidence must support a project-level health verdict. Handle general risk questions, personal health checks, and narrow standalone inspections directly. Explicit invocation selects the full Project Audit behavior.

## Not for
- Fixing issues found during the audit.
- Reviewing a specific change, PR, patch, or commit; use `change-review`.
- Tracing a specific failure to root cause; use `root-cause-analysis`.
- Shipping a completed branch; use `shipping`.
- Designing new product behavior; use `product-planning`.
- Context Survey briefs about a narrow question; use `context-survey`.

## Outcome contract
Deliver a project audit report where every finding maps:

`finding -> evidence -> impact -> confidence -> next Keystone module`

The report must include:
- audit scope and evidence inspected;
- concrete checklist status for tooling/CI drift, docs-vs-reality, config/env rot, dependency health, test health/flakiness, package/release health, and instruction/skill drift;
- risks ranked by severity and confidence using the Project Audit priority rubric;
- checks not run and why;
- explicit no-fix confirmation unless repairs were requested.

Project Audit priority rubric:
- **Critical:** Broken now, release-blocking, security-sensitive, data-loss-prone, or prevents required project operation. Urgency: act before `shipping` or before depending on the affected subsystem. Next Keystone module: usually `root-cause-analysis` for failing behavior or `implementation` for repairs; use `shipping` only for release gate follow-up after the issue is fixed.
- **Watch:** Risky, stale, drifting, or likely to become blocking, but not proven broken under current evidence. Urgency: schedule remediation or investigation soon; do not let it become untracked backlog. Next Keystone module: usually `context-survey` to verify unknowns, `task-creation` to plan multi-step remediation, or `implementation` for contained repairs.
- **Info:** Health signal, minor inconsistency, low-impact cleanup, or explicitly unknown/unchecked area. Urgency: no immediate action unless priorities change. Next Keystone module: `none` when informational, or `change-review`/`shipping` when the next step is validation rather than repair.

## Modes
- **Project snapshot:** summarize structure, active areas, scripts, tests, CI, docs, and current branch state.
- **Tooling/CI drift audit:** compare manifests, scripts, Make targets, task runners, hooks, CI workflows, matrix versions, cache keys, and required checks against actual files and commands.
- **Docs-vs-reality audit:** compare README, contributor docs, runbooks, release docs, examples, and command snippets with actual repo layout and executable scripts.
- **Config/env rot audit:** insp

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: refactoring
description: Program source-code refactoring for an explicit structural code improvement to structure, ownership, types, or duplication that preserves identified executable behavior. Select only when the request requires a structural code change with project-specific invariant proof, or enters through a canonical handoff from another Keystone skill.
---

# Refactoring

## Core principle

Refactoring changes structure while preserving behavior. Improve design in small, reversible steps, with characterization or regression proof when behavior could drift.

## Load when

Load for an existing software project when the user asks to improve code structure while preserving an identified behavior contract: extract or inline code, reduce duplication, clarify names or type boundaries, remove code smells, or reorganize ownership.

If the user wants behavior change, use `implementation`. If a failure cause is unknown, use `root-cause-analysis`. If the refactor is broad or risky, create a refactor doc before mutation.

At entry, use the full Keystone path when the work changes integrated project code and needs project-specific invariant proof. Handle isolated text cleanup, mechanical formatting, and standalone snippets directly. Explicit invocation selects the full Refactoring behavior.

## Outcome contract

A complete refactor reports:

- the behavior invariant that must not change;
- smells or pressures addressed;
- isolation checked before mutation via `../../references/gates/isolation.md`;
- characterization/regression proof used before risky edits;
- files changed and why each changed;
- verification commands/results or explicit proof gaps;
- checkpoint handoff to `change-review` when review is needed.

## Process

1. Classify size and risk.
   - Small/local: one area, clear invariant, existing proof likely enough.
   - Large/cross-cutting: multiple boundaries, weak coverage, shared contracts, or context-window risk.
   - Completion criterion: refactor path is either safe for direct mutation or documented first.
2. For large refactors, write a refactor doc under `docs/keystone/refactors/YYYY-MM-DD-<slug>.md` before editing.
   - Include goal, invariants, smells, affected areas, slices, proof, rollback, and review focus.
   - Completion criterion: doc is specific enough for `task-creation` or `implementation`.
3. Pass isolation before mutation.
   - Load/check `../../references/gates/isolation.md`.
   - Respect unrelated dirty files and protected scope.
   - Completion criterion: mutation scope is safe.
4. Establish behavior proof.
   - Prefer existing behavior tests; add characterization coverage when the invariant lacks a tripwire.
   - Completion criterion: there is a tripwire for accidental behavior change or a documented proof gap.
5. Apply small refactorings.
   - Prefer rename, extract, inline, move, split, consolidate, simplify conditionals, remove dead code, and clarify ownership.
   - Keep public contracts stable unless explicitly approved.
   - Completion criterion: each step is understandable and reversible.
6. Use engineering standards.
   - Load `../../references/engineering-standards.md` for architecture or ownership decisions.
   - Remove abstractions that lack current pressure.
   - Completion criterion: the result has clearer ownership, state, naming, or boundaries.
7. Verify.
   - Load and pass `../../references/gates/proof.md` for the preserved invariant.
   - Completion criterion: behavior invariant is supported by observed evidence.
8. Checkpoint and hand off.
   - Use `../../references/gates/checkpoint.md`.
   - Hand off to `change-review` for non-trivial refactors or leave an explicit review pointer.

## Smell prompts

Investigate duplication, long functions, god objects, feature envy, primitive obsession, data clumps, shotgun surgery, divergent change, hidden control flow, speculative generality, vague managers/helpers, mixed abstraction levels, duplicated state, and unclear ownership.

##

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: root-cause-analysis
description: Project debugging for a concrete failure in a software or product system. Use for a reproducible or evidence-bearing regression, failing test/build, runtime or integration defect, flake, data corruption, or performance anomaly, or when another Keystone skill needs the cause proven.
---

# Root-Cause Analysis

## Core principle
Find the root cause before fixing. Root-cause analysis is an evidence ladder: observe the failure, reproduce it, minimize it, trace the mechanism, test falsifiable hypotheses, prove the cause, fix narrowly, guard against regression, verify with exact output, and clean up. No guess-and-check, no cargo-cult edits, no shipping/finalization work.

## Load when
Load when the user reports a concrete failure in a software project or product system: a failing test/build, broken runtime behavior, regression, flaky result, performance anomaly, integration failure, suspicious system logs, silent failure, or data corruption.

Also load when the task involves:
- deciding whether a failure is local, historical, environmental, data-dependent, timing-dependent, or cross-system;
- diagnosing nondeterminism, race conditions, retries, timeouts, queues, caches, or distributed boundaries;
- interpreting logs/traces/metrics to explain a symptom;
- proving whether a suspected fix actually addresses the cause.

At entry, use the full Keystone path when the failure belongs to a project artifact or operated product and evidence can be gathered from its code, tests, builds, telemetry, or runtime. Handle general explanations of error messages and non-project troubleshooting directly. Explicit invocation selects the full Root-Cause Analysis behavior.

## Not for
- Implementing new behavior unrelated to the failure.
- General code improvements without a reproduced problem.
- Release finalization, merge strategy, or deployment handoff; use `shipping` after proof and review.
- Broad repository audits; use `project-audit`.
- Spec decisions where no failure exists; use `product-planning`.
- Replacing review, test strategy, or gate validation modules.

## Outcome contract
Deliver a root-cause analysis report with:
- symptom, impact, affected users/systems, and failure classification;
- reproduction steps, exact command/input/environment, or why reproduction was not possible;
- minimized failing case when feasible, including what was removed and what still fails;
- evidence gathered through logs, tests, code inspection, history, metrics, traces, or instrumentation;
- hypotheses considered, which were disproven, and the surviving root-cause hypothesis;
- proof that the root cause explains the symptom and predicts observed behavior;
- exact fix made or proposed, scoped to the proven cause;
- regression test, guard, monitor, or explicit reason none is feasible;
- verification commands and exact results/output evidence;
- cleanup performed, temporary diagnostics removed, and remaining uncertainty or escalation.

Stop only when one of these is true:
- the root cause is proven, the narrow fix is verified, and regression protection is in place or justified;
- reproduction is impossible after documented attempts and the best available evidence has been preserved;
- escalation criteria are met.

## Modes
- **Triage:** classify severity, scope, reproducibility, recency, ownership, and risk before fixing.
- **Reproduce/minimize:** create the smallest reliable case that demonstrates the failure.
- **Instrument/trace:** add temporary logs, probes, traces, assertions, metrics, or diagnostics to observe reality.
- **Hypothesis test:** test one falsifiable explanation at a time and record pass/fail evidence.
- **Fix:** make the smallest change that addresses the proven root cause.
- **Stabilize flaky behavior:** collect repeated runs, isolate nondeterminism, and prove the stabilizing change.
- **Performance investigation:** measure baseline, localize bottleneck, prove causality, then optimize narrowly.
- **Log/si

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: shipping
description: Project shipping is authorized immediate delivery execution for identified, already-completed software work. Select only when the user explicitly authorizes an immediate concrete action to commit, push, prepare or create a PR, merge, tag, package, publish, release, deploy, perform an exact repository handoff, or perform destructive cleanup of an exact named completed-delivery target. A canonical handoff qualifies only when it carries the verbatim explicit delivery request and a non-empty exact authorized action set. Context Survey owns pre-authorization cleanup-target reconnaissance while approval is pending.
---

# Shipping

## Core principle
Shipping is deterministic finalization for already-completed work. It proves, reviews, packages, and hands off a release or PR; it never sneaks in new implementation or last-mile fixes.

A shipping decision consumes three shared contracts: load `../../references/gates/proof.md`, `../../references/gates/review.md`, and `../../references/gates/ship.md`. Those files own pass/fail; Shipping gathers evidence and performs explicitly authorized delivery mechanics.

If a final check fails, follow its owning gate's fail action. Final delivery remains blocked until the required gates pass.

## Load when
Load only when the user explicitly asks to deliver completed software project work:
commit it, push it, prepare or create a PR, merge, tag, package, publish, release, deploy, or
perform an exact repository handoff or destructive cleanup of a named completed-delivery
target.

For a Keystone handoff, load `../../references/handoff-packet.md`. The canonical packet's
`evidence` field must carry the verbatim user delivery request and exact authorized
action set. Before acting, derive the effective action set using the packet's
current-intent reconciliation rule. A handoff without carried authorization does not
qualify for Shipping.

At entry, use the full Keystone path when an identified repository change, package,
release candidate, or deployment is complete enough for gates and the user has
explicitly requested a delivery outcome. Handle ordinary summaries, status updates,
and non-project handoffs directly. Explicit skill invocation selects the Shipping
workflow; commit, push, prepare or create a PR, merge, tag, package, publish, release,
deploy, perform an exact repository handoff, or perform destructive cleanup of an
exact completed-delivery target only when that action is in the user's authorized
action set and the gates authorize it.

## Not for
- Starting new implementation or sneaking in last-minute fixes.
- Unfinished code, product, migration, or feature cleanup; route that work to `implementation`. Shipping owns destructive cleanup only for an exact completed-delivery target under explicit user authorization.
- Root-cause debugging; use `root-cause-analysis`.
- Fixing test/build/package failures; use `implementation` for contained repairs or `root-cause-analysis` when the cause is unclear.
- General project risk audits; use `project-audit`.
- Reviewing code quality of a specific change; use `change-review`.
- Shaping unfinished requirements; use `product-planning`.
- Bypassing proof, change-review, package, deploy, or human release approvals.

## Outcome contract
Deliver a strict shipping packet that includes:
- current branch/worktree status and cleanliness;
- scope of completed work and explicit non-scope;
- proof gate evidence with commands/artifacts/results;
- review gate evidence or exact pending review status;
- shipping gate evidence including CI/CD status, deploy preview/staging status when applicable, package/release readiness, rollback plan, and handoff actions;
- multi-target package/release notes where applicable;
- changelog/release-note text or summary;
- unresolved risks and go/no-go verdict;
- authorized action set;
- attempted actions with each exact target and result/status;
- partial completion status, including remaining or unattempted action

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: task-creation
description: Project delivery breakdown for a concrete software or product goal. Use when that goal needs implementation slices, milestones, dependencies, verification gates, or agent-ready work, or when another Keystone skill hands off a shaped goal for sequencing.
---

# Task Creation

## Core principle
Task Creation turns a goal into sequenced, reviewable vertical slices of work.

A good task-creation makes implementation easier because every slice has a visible result, clear constraints, and a verification path. It makes review easier because reviewers can compare changes against stated goals, requirements, risks, and acceptance checks.

Task Creation is sequencing, not execution. A task-creation is not proof; only inspected changes, tests, demos, or other evidence prove completion.

## Load when
Load for a concrete software or product project when the user asks to:

- break down a feature, fix, refactor, migration, tool, system, or project
- produce milestones, implementation steps, tickets, issues, vertical slices, or phases
- decide sequencing, dependencies, iterations, scope cuts, or parallelization
- turn an approved or sufficiently shaped goal into implementable work
- prepare work for coding agents, reviewers, or subagents
- sequence greenfield architecture after the core users, runtime, and tradeoffs are stable enough to slice
- split a large task into reviewable chunks without exposing another public command

Also load when implementation is requested but the goal is broad enough that coding immediately would hide major sequencing decisions. If behavior, scope, UX, or architecture tradeoffs are still undecided, route to `product-planning` first; use Task Creation once the desired outcome is stable enough to sequence.

At entry, use the full Keystone path for project delivery work tied to a repository, product initiative, approved specification, or engineering lifecycle outcome. Handle standalone lists, personal planning, and ordinary to-do decomposition directly. Explicit invocation selects the full Task Creation behavior.

## Not for
Do not use Task Creation for:

- implementation, file edits, refactors, migrations, or generated code
- debugging a known failure; use `root-cause-analysis` first, then return to Task Creation if a repair sequence is needed
- context-survey-only tasks; use `context-survey` first when facts are missing
- copy/design shaping as the primary work; use `product-planning` first when output is prose, UX, or design direction
- final verification, release readiness, or completion claims; use `change-review`, `project-audit`, or `shipping`

## Outcome contract
A Task Creation output must include:

1. Goal: the intended outcome in one or two sentences.
2. Context inspected: files, docs, requirements, or assumptions used.
3. Requirements inventory: critical requirements, non-functional requirements, good-to-haves, constraints, and open questions.
4. Stack and architecture context: current or proposed technologies, boundaries, integrations, and limitations.
5. Iteration layering: iteration 1, iteration 2, iteration 3, etc., with explicit scope cuts.
6. Vertical slices: ordered work items that each deliver an end-to-end outcome.
7. Verification gates: how each slice can be tested, reviewed, or demonstrated.
8. Risks and dependencies: what can block, invalidate, or reorder the work.
9. Handoff: recommended next primary module and any subagent/analysis-depth suggestions.

If information is missing, state the assumption or ask the smallest set of questions required to avoid a bad task-creation.

## Modes

### Feature task-creation
Use for new capabilities in an existing product. Focus on the user/operator goal, existing entry points, data paths, APIs, UI surfaces, tests, deployment constraints, and the smallest end-to-end slice that proves the feature path. Add progressive enrichment after the core loop works. Avoid horizontal buckets like "database", "backend", "frontend", an

Preview of the first 4,000 characters. Read full instructions →