@laitszkin/apollo-toolkit 3.8.3 → 3.9.0

package/develop-new-features/SKILL.md

@@ -1,134 +1,74 @@
 ---
 name: develop-new-features
 description: >-
-  Spec-first feature development workflow for new behavior and greenfield
-  features. Depends on `generate-spec` for shared planning artifacts and
-  `test-case-strategy` for risk-driven test selection before coding, then
-  implements the approved feature with focused validation.
-  Use when users ask to design or implement new features, change product
-  behavior, request a planning-first process, or ask for a greenfield feature.
-  Once the approved spec set exists and implementation begins, complete all
-  planned tasks and applicable checklist items before yielding unless the user
-  changes scope or an external blocker prevents safe completion.
-  Tests must not stop at happy-path validation: for business-logic changes
-  require property-based testing unless explicitly `N/A` with reason, design
-  adversarial/regression/authorization/idempotency/concurrency coverage where
-  relevant, use mocks for external services in logic chains, and verify
-  meaningful business outcomes rather than smoke-only success.
+  Net-new or materially new product behavior: **`generate-spec`** is mandatory (clarify → approve → only then code) with **`test-case-strategy`** backing every serious logic change—property tests required unless documented `N/A`, add adversarial/auth/idempotency/concurrency/mocks for external services, cap each spec at three modules and split coordinated batches via `coordination.md`, finish every approved `tasks.md`/`checklist.md` item or document deferrals.
+  Use when users ask for “new feature”, “greenfield slice”, “plan-first delivery”. Reroute typo-only UI, bug restores, or internal refactors without product impact to **`enhance-existing-features`** / **`systematic-debug`**.
+  Bad: editing `src/api.ts` before approval exists… Good: spec records risk → tests map to requirement IDs… Typo fix in footer copy → wrong skill…
 ---
 
 # Develop New Features
 
 ## Dependencies
 
-- Required: `generate-spec` for `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, `design.md`, clarification handling, approval gating, and completion-status backfill; `test-case-strategy` for risk-driven test selection, meaningful oracle design, and unit drift checks.
+- Required: `generate-spec` for shared planning artifacts and `test-case-strategy` for risk-driven test selection, oracles, and unit drift checks before coding.
 - Conditional: none.
 - Optional: none.
-- Fallback: If `generate-spec` or `test-case-strategy` is unavailable, stop and report the missing dependency.
+- Fallback: **`generate-spec`** **or** **`test-case-strategy`** missing ⇒ **stop** (no improvised planning/tests).
 
-## Standards
+## Non-negotiables
 
-- Evidence: Review authoritative docs and the existing codebase before planning or implementation.
-- Execution: Use specs only for feature work that is genuinely multi-step, cross-surface, or higher risk; skip specs for obviously small/localized work and route that work to direct implementation or the appropriate maintenance skill instead.
-- Quality: Use `test-case-strategy` to add risk-based tests with property-based, regression, integration, E2E, adversarial, and rollback coverage when relevant.
-- Output: Keep the approved planning artifacts and the final implementation aligned with actual completion results.
+- This skill applies to **non-trivial new behavior / greenfield**. **MUST NOT** activate for: pure bug restore; style/copy-only tweaks; trivial one-pocket config/constants; internal-only refactors/no visible behavior—these routes belong to **`enhance-existing-features`**, **`systematic-debug`**, etc., **without** new specs here.
+- **When this skill applies**, **`generate-spec` is mandatory** before product code: create/update plans, BDD reqs, contracts, design, optional batch **`coordination.md`**, obtain **explicit approval**, then implement.
+- **≤3 modules** per spec set; wider work ⇒ multiple **independent** spec sets under batch + **`coordination.md`** (no hidden cross-deps).
+- **MUST NOT** modify product code **before** approval.
+- Post-approval: **all** in-scope **`tasks.md`/`checklist.md`** items complete unless deferral/blocker documented in artifacts.
+- **`test-case-strategy`**: risk-first; property-based logic **required** unless documented **`N/A`**; adversarial/auth/idempotency/concurrency where relevant; mocks for externals in logic chains; oracles tied to requirements.
+- Backfill all plan files + coordination when batch; no fake-completed template branches.
 
-## Goal
+## Standards (summary)
 
-Use a shared spec-generation workflow for non-trivial new feature work, then implement the approved behavior with strong test coverage and minimal rework.
+- **Evidence**: Official docs + repo architecture pass before plan lock.
+- **Execution**: Route-out trivial work → spec → implement → test → backfill.
+- **Quality**: Plans trace to tests; minimal speculative code.
+- **Output**: Approved scope shipped + honest plan status.
 
 ## Workflow
 
-### 1) Review authoritative docs first
-
-- Identify the stack, libraries, APIs, and external dependencies involved.
-- Use official documentation as the source of truth.
-- Prefer Context7 for framework/library APIs; use web for the latest official docs when needed.
-- Record only the references required for this feature.
-
-### 2) Run `$generate-spec`
-
-- First decide whether the request truly belongs in this skill.
-- Do not use this skill or generate specs when the request is actually one of these:
-  - bug fixes or regressions that restore intended behavior without introducing new product behavior
-  - copy-only, styling-only, spacing-only, layout-only, or other purely presentational UI tweaks with localized impact
-  - simple configuration, constant, feature-flag, dependency, or content updates confined to one small area
-  - small refactors, naming cleanups, or internal code-health work with no externally visible behavior change
-  - narrowly scoped adjustments that touch only a few files/modules and do not require cross-team alignment or approval artifacts
-- In those cases, do not create planning docs; instead use the appropriate direct implementation workflow (for example `enhance-existing-features` for small brownfield adjustments or `systematic-debug` for bug fixes).
-- Specs are required when the request is truly a non-trivial new feature, product behavior change, or greenfield project that needs shared planning.
-- Treat each spec set as a narrowly scoped workstream that covers at most three modules.
-- If the requested change would require edits across more than three modules, do not force it into one oversized spec set.
-- Instead, split the work into multiple independent spec sets, each covering no more than three modules.
-- Define those spec sets so they do not conflict with each other and do not depend on another spec set being implemented first in order to be valid.
-- When multiple spec sets belong to one coordinated feature batch, place them under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` and create one shared `coordination.md` at the batch root for shared preparation, ownership boundaries, replacement direction, and merge order.
-- Follow `$generate-spec` completely for:
-  - generating `docs/plans/{YYYY-MM-DD}/{change_name}/...` for single-spec work, or `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/...` plus `coordination.md` for parallel batches
-  - filling BDD requirements and risk-driven test plans
-  - documenting external dependency contracts in `contract.md` when they materially constrain the feature
-  - documenting the architecture/design delta in `design.md`
-  - documenting shared preparation and implementation direction in `coordination.md` when multiple spec sets will be implemented in parallel
-  - handling clarification responses
-  - obtaining explicit approval before coding
-  - backfilling document status after implementation and testing, including requirement completion in `spec.md`
-- Do not modify product code before the approved spec set exists.
-
-### 3) Explore architecture and reuse opportunities
-
-- Trace entrypoints, module boundaries, data flow, and integration points relevant to the new behavior.
-- Identify reusable components, patterns, and configuration paths before adding new code.
-- Keep a concise map of likely files to modify so implementation stays scoped.
-
-### 4) Implement after approval
-
-- Reuse existing patterns and abstractions when possible.
-- Keep changes focused and avoid speculative scope expansion.
-- Update environment examples only when new inputs are actually required.
-- Once approval is granted and implementation starts, treat every unchecked in-scope item in `tasks.md` and every applicable item in `checklist.md` as required work for this run.
-- Do not stop after a partial implementation, partial test pass, or partial doc backfill when work remains in the approved plan.
-- Only pause before completion if:
-  - the user changes scope or explicitly asks to stop
-  - a new clarification invalidates the approved plan and requires renewed approval
-  - an external blocker (missing credentials, unavailable dependency, access restriction, broken upstream system) prevents safe completion
-- When blocked, record the exact unfinished items and blocker in the plan artifacts before yielding.
-
-### 5) Testing coverage (required)
-
-Use `$test-case-strategy` for every non-trivial change.
-
-- Start from risk inventory and requirement IDs, not from the happy path.
-- Define test oracles before implementation and map them to `spec.md`, `tasks.md`, and `checklist.md`.
-- For each atomic task that changes non-trivial local logic, define a focused unit drift check or record the smallest replacement verification with a concrete `N/A` reason.
-- Add unit, regression, property-based, integration, E2E, adversarial, mock/fake, rollback, or no-partial-write coverage only when the risk profile warrants it.
-- Each planned test must have a meaningful oracle: exact business output, persisted state, emitted side effects, or intentional lack of side effects.
-- Run relevant tests when possible and fix failures.
-
-### 6) Completion updates
-
-- Backfill `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` through `$generate-spec` workflow after implementation and testing.
-- If the feature used a parallel batch, also backfill `coordination.md` with any final shared preparation, cutover, or ownership changes that emerged during execution.
-- In `spec.md`, mark each approved requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
-- Mark every completed task in `tasks.md`.
-- In `checklist.md`, update only the items that are actually applicable to the approved scope and executed validation.
-- In `contract.md`, keep the final external dependency contract records aligned with the implementation and verified upstream constraints.
-- In `design.md`, keep the final architecture/design description aligned with the implementation that actually shipped.
-- Do not mark template alternatives, unused example rows, or non-applicable decision branches as completed just to make the file look fully checked.
-- Rewrite, remove, or leave `N/A` on template-only sections so the final checklist reflects the real work rather than the starter template.
-- Explicitly label any truly remaining applicable item as deferred or blocked with the reason.
-- Report the implemented scope, test execution, and any concrete `N/A` reasons.
-
-## Working Rules
-
-- By default, write planning docs in the user's language.
-- Keep implementation traceable to approved requirement IDs and planned risks.
-- Keep each spec set limited to at most three modules; split larger changes into independent, non-conflicting, non-dependent spec sets before approval.
-- When multiple spec sets are used for one feature batch, keep cross-spec rules in `coordination.md` rather than repeating them in every `design.md`.
-- Prefer realism over rigid templates: add or remove test coverage only when the risk profile justifies it.
-- Every planned test should justify a distinct risk; remove shallow duplicates that only prove the code "still runs".
-- Treat starter template alternatives as mutually exclusive options, not as boxes that all need to be checked.
-- If a spec set exists and approval has been granted, do not yield with unfinished in-scope tasks or checklist items unless the user approves a deferment or an external blocker makes completion impossible.
+**Chain-of-thought:** If request is maintenance-sized, **`Pause →`** “Should I reroute?” before spending tokens on **`generate-spec`**.
+
+### 1) Docs & routing
+
+- Stack/deps discovery; verify using official sources.
+  - **Pause →** Is this truly greenfield/feature vs fix/polish—if latter, bail to other skill?
+
+### 2) `generate-spec`
+
+- Full workflow: dirs `docs/plans/{YYYY-MM-DD}/…`, batch/coord flags, clarification, **`MUST`** approval before code.
+  - **Pause →** Did I secretly start coding “just the types”—**hard violation**?
+
+### 3) Architecture map
+
+- Reuse seams; list likely files **after** approval to stay honest to plan.
+
+### 4) Implement (post-approval)
+
+- Execute tasks/checklist exhaustively unless blocker recorded with user-visible deferrals.
+
+### 5) Testing
+
+- **`test-case-strategy`** mapping requirement IDs ↔ tests; drift checks/`N/A` discipline; run and fix reds.
+
+### 6) Completion
+
+- Backfill **`generate-spec`**-style across **`spec/tasks/checklist/contract/design`** (+ **`coordination.md`**); requirement-level status in **`spec.md`**; strip template illusions; final report with scope + tests + `N/A`.
+
+## Sample hints
+
+- **Wrong skill**: “Fix typo in footer string” ⇒ not here.
+- **Right skill**: “Add export-to-CSV for dashboard” ⇒ **`generate-spec`** then code + property tests on CSV invariants maybe.
+- **Split**: Touches CLI + server + terraform module boundaries—three modules cap ⇒ **two spec dirs** coordinated.
 
 ## References
 
-- `$generate-spec`: shared planning and approval workflow.
-- `$test-case-strategy`: shared test selection, oracle design, and unit drift-check workflow.
+- **`generate-spec`**: planning/backfill authority
+- **`test-case-strategy`**: breadth/depth of tests

package/enhance-existing-features/SKILL.md

@@ -1,143 +1,77 @@
 ---
 name: enhance-existing-features
 description: >-
-  Extend brownfield features by exploring the codebase first, then deciding
-  whether shared planning docs (`spec.md`/`tasks.md`/`checklist.md`/`contract.md`/`design.md`) are required
-  before coding. When specs are needed, use `generate-spec` for planning,
-  clarification, approval, and backfill, and complete approved in-scope tasks
-  before yielding unless scope changes or an external blocker prevents safe
-  completion. With or without specs, use `test-case-strategy` to select and
-  run relevant unit, property-based, regression, integration, E2E, adversarial,
-  mock/fake, and drift-check coverage, and verify meaningful business outcomes
-  instead of smoke-only success.
+  Extend brownfield systems only after reading the real modules involved: choose **`generate-spec`**/`recover-missing-plan` when user-visible scope, ambiguity, coordination, or sensitive flows demand written approval; otherwise implement directly but still run **`test-case-strategy`** on every non-trivial delta (property/adversarial/integration as risk dictates) and never check off plans without commit+test evidence.
+  Use for backlog work that mutates production behavior; reroute pure regressions, copy/style-only tweaks, or single-pocket config nits that restore documented intent without new surface area.
+  Bad: multi-service permission change with zero spec… Good: contract captures external API limits + property tests cover invariants… Single-file pagination fix matching README → targeted regression only…
 ---
 
 # Enhance Existing Features
 
 ## Dependencies
 
-- Required: `test-case-strategy` for risk-driven test selection, meaningful oracle design, and unit drift checks.
-- Conditional: `generate-spec` for shared planning docs when spec-trigger conditions are met; `recover-missing-plan` when the user points to a required `docs/plans/...` spec set that is missing, archived, or mismatched in the current workspace.
+- Required: `test-case-strategy` for risk selection, oracles, drift checks.
+- Conditional: **`generate-spec`** when spec triggers below fire; **`recover-missing-plan`** when user-named `docs/plans/...` is missing/archived/mismatched.
 - Optional: none.
-- Fallback: If `test-case-strategy` is unavailable, stop and report the missing dependency. If specs are required and `generate-spec` is unavailable, stop and report the missing dependency.
+- Fallback: **`test-case-strategy`** unavailable ⇒ **stop**. Spec path required but **`generate-spec`** unavailable ⇒ **stop**.
 
-## Standards
+## Non-negotiables
 
-- Evidence: Explore the existing codebase first and verify the latest authoritative docs for the involved stack or integrations.
-- Execution: Decide whether specs are required from the actual change surface, run `generate-spec` when needed, then continue through implementation, testing, and backfill until the active scope is fully reconciled; when the user asks for a specific final behavior or architectural end state, do not substitute a preparatory or partial milestone unless the user explicitly re-scopes the request.
-- Quality: Use `test-case-strategy` to add risk-based tests with property-based, regression, integration, E2E, adversarial, and rollback coverage when relevant.
-- Output: Keep implementation and any planning artifacts traceable, updated, and aligned with actual completion results.
+- **MUST** explore relevant code (entrypoints, flows, integrations) **before** deciding process or editing—**MUST NOT** spec-dump or code-dump from titles alone.
+- Spec path **when** any: new/changed **user-visible** behavior (not mere restore of old intent); ambiguity needing approval; multi-module alignment; critical/sensitive/irreversible/migration risk; traceability materially reduces error.
+- **MUST NOT** open **`generate-spec`** for clearly tiny/localized work: pure regression to prior intent; polish-only UI copy/style; one-area config/constant/flag; narrow CRUD/validation tweak; internal refactor/observability **without** behavior change—**implement + `test-case-strategy` directly**.
+- If specs: **MUST** complete **`generate-spec`** lifecycle (approval before code; backfill after); **≤3 modules** per spec set—split independent non-dependent sets + batch `coordination.md` when coordinated parallelism; **MUST NOT** code pre-approval.
+- **MUST NOT** yield with approved in-scope **`tasks.md`/`checklist.md`** undone except user deferral or documented external blocker (record in plans).
+- **`test-case-strategy` required** for non-trivial deltas—property/adversarial/integration etc. per risk; meaningful oracles; drift check or explicit **`N/A`** with reason per non-trivial logic task.
+- External deps: **`contract.md`** records official-backed obligations when material.
+
+## Standards (summary)
+
+- **Evidence**: Code exploration + official docs/APIs where touched.
+- **Execution**: Explore → decide specs → docs/officials → implement → test → backfill/summary.
+- **Quality**: No speculative scope expansion; reuse patterns.
+- **Output**: Behavior matches ask; traceable tests; plans honest if specs used.
 
 ## Workflow
 
-### 1) Explore codebase first
-
-- Read the relevant existing code before deciding process or editing anything.
-- Locate entrypoints, configuration, and primary data flow.
-- Trace module relationships (imports, call graph, shared models, side effects).
-- Identify integration points (DB, RPC, external APIs, queues, filesystems).
-- Identify user-critical logic chains affected by the change.
-- Summarize findings and the likely change surface before editing.
-
-### 2) Decide whether specs are required from the requested change
-
-Use the user's requested change together with the codebase exploration results to decide whether to generate specs.
-
-Trigger specs when any of the following is true:
-- the change introduces new user-visible behavior, not just a bug fix restoring intended behavior
-- requirements are ambiguous enough that approval on written scope, tradeoffs, or edge cases is useful
-- multiple modules, layers, services, or teams must stay aligned
-- the change touches critical flows, sensitive data, permissions, money movement, migrations, or irreversible operations
-- the risk profile is high enough that explicit requirement-to-test traceability will materially reduce mistakes
-
-Do not generate specs when the work is clearly small and localized, such as:
-- bug fixes or regressions that restore already-intended behavior without changing product scope
-- pure frontend polish: copy tweaks, styling, spacing, alignment, responsive touch-ups, visual cleanup, or simple template/view wiring
-- small configuration, constant, dependency, content, or feature-flag updates confined to one area
-- straightforward CRUD field additions, validation message tweaks, or one-path handler adjustments with limited blast radius
-- refactors, renames, dead-code cleanup, or observability-only changes that do not alter user-visible behavior
-
-When in doubt, prefer direct implementation for genuinely low-risk localized changes, and reserve specs for changes whose scope or risk would benefit from explicit approval artifacts.
-
-If triggered:
-- If the user already points to a specific `docs/plans/...` path and that plan set is missing or mismatched in the current workspace, run `$recover-missing-plan` before deciding whether to continue implementation or backfill.
-- Run `$generate-spec` and follow its workflow completely.
-- Use it to create or update `docs/plans/{YYYY-MM-DD}/{change_name}/spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md`.
-- Keep each spec set scoped to at most three modules.
-- If the requested change would require edits across more than three modules, split it into multiple spec sets instead of drafting one large coupled plan.
-- Design the split spec sets so they are independently valid, do not conflict with each other, and do not require another spec set to land first.
-- When multiple spec sets are created for one coordinated change, place them under `docs/plans/{YYYY-MM-DD}/{batch_name}/{change_name}/` and maintain one batch-level `coordination.md` that records shared preparation, ownership boundaries, replacement direction, and merge order.
-- Ensure planned behaviors and edge cases cover external dependency states, abuse/adversarial paths, and any relevant authorization/idempotency/concurrency/data-integrity risks.
-- When external dependencies materially constrain the change, make sure `contract.md` captures their official-source-backed invocation surface, constraints, and caller obligations.
-- Make sure `design.md` captures the architecture/design delta, affected modules, control flow, and tradeoff decisions for the approved scope.
-- After implementation and testing, update the same plan set so `spec.md` reflects requirement completion status in addition to task and checklist progress.
-- If users answer clarification questions, update the planning docs and obtain explicit approval again before implementation.
-- Do not modify implementation code before approval.
-- Once approval is granted, do not stop with unchecked in-scope items remaining in `tasks.md` or applicable unchecked items in `checklist.md` unless the user explicitly defers them or an external blocker prevents safe completion.
-
-If not triggered:
-- Continue directly with the same downstream workflow below.
-
-### 3) Verify latest authoritative docs
-
-- Identify the tech stack, libraries, and external dependencies involved.
-- Use official documentation as the source of truth.
-- Prefer Context7 for framework/library APIs; use web for latest official docs.
-- If required docs are private or missing, request access or user-provided references.
-
-### 4) Implement the feature
-
-- Reuse existing patterns and abstractions; avoid over-engineering.
-- Keep changes focused and minimal; preserve current behavior unless required.
-- Follow project conventions (naming, linting, formatting, configuration).
-- Update environment examples only when new inputs are required.
-- If specs exist, treat every unchecked in-scope task and applicable checklist item as part of the required deliverable for this run.
-- Do not stop after partial code changes, partial tests, or partial backfill when approved planned work remains.
-- Do not present an enabling first stage, temporary coalescing step, or other intermediate milestone as complete when the user asked for the final scoped behavior.
-- Only pause before completion if:
-  - the user changes scope or explicitly asks to stop
-  - new clarification requires plan updates and renewed approval
-  - an external blocker (missing credentials, unavailable dependency, access restriction, broken upstream system) prevents safe completion
-- When blocked, record the exact unfinished items and blocker in the spec set before yielding.
-
-### 5) Testing coverage (required with or without specs)
-
-Use `$test-case-strategy` for every non-trivial change, even when specs are skipped.
-
-- Start from risk inventory and changed behavior, not from the happy path.
-- Define test oracles before implementation when the change is planned, and before finalizing tests when the change is discovered during brownfield exploration.
-- For each atomic task that changes non-trivial local logic, define a focused unit drift check or record the smallest replacement verification with a concrete `N/A` reason.
-- Add unit, regression, property-based, integration, E2E, adversarial, mock/fake, rollback, or no-partial-write coverage only when the risk profile warrants it.
-- Each planned test must have a meaningful oracle: exact business output, persisted state, emitted side effects, or intentional lack of side effects.
-- Run relevant tests when possible and fix failures.
-
-### 6) Completion updates
-
-- If specs were used, backfill `spec.md`, `tasks.md`, `checklist.md`, `contract.md`, and `design.md` through `$generate-spec` workflow based on actual completion and test outcomes.
-- If the change used a parallel batch, update `coordination.md` whenever shared preparation, legacy replacement direction, or merge constraints changed during execution.
-- In `spec.md`, mark each relevant requirement with its actual completion state, such as completed, partially completed, deferred, or not implemented, plus brief evidence or rationale where needed.
-- If specs were used, mark every completed task in `tasks.md`.
-- If specs were used, update only the applicable checklist items that correspond to real scope, chosen test strategy, and actual execution.
-- If specs were used, update `contract.md` so the documented dependency obligations and constraints match the implemented reality.
-- If specs were used, update `design.md` so the architecture/design record matches the delivered implementation.
-- Do not mark unused template examples, mutually exclusive alternatives, or non-applicable branches as completed.
-- Remove, rewrite, or leave `N/A` on starter-template items when they do not belong to the real change.
-- Explicitly label any still-applicable remaining item as deferred or blocked with the reason.
-- If specs were not used, provide a concise execution summary including test IDs/results, regression coverage, mock scenario coverage, adversarial coverage, and any `N/A` reasons.
-
-## Working Rules
-
-- Keep the solution minimal and executable.
-- Always decide the need for specs only after exploring the existing codebase.
-- When specs are used, keep each spec set limited to at most three modules; split broader work into independent, non-conflicting, non-dependent spec sets before approval.
-- When specs are split for parallel worktree implementation, keep batch-wide rules only in `coordination.md` rather than copying them into every spec-local `design.md`.
-- Maintain traceability between requirements, tasks, and tests when specs are present.
-- Treat checklists as living artifacts: adjust items to match real change scope.
-- Treat mutually exclusive template choices as a decision to record, not multiple boxes to finish.
-- Every planned test should justify a distinct risk; remove shallow duplicates that only prove the code "still runs".
-- If a spec set exists and approval has been granted, do not yield with unfinished in-scope tasks or checklist items unless the user approves a deferment or an external blocker makes completion impossible.
+**Chain-of-thought:** **`Pause →`** after explorations and spec decision—wrong classification wastes days.
+
+### 1) Explore codebase
+
+- Map modules, integrations, blast radius.
+  - **Pause →** Can I state **one paragraph** concrete change surface before editing?
+
+### 2) Decide specs
+
+- Apply Non-negotiable triggers above; if doubt favors **implement-only** **only when** genuinely low-risk localized.
+- If specs: broken path ⇒ **`recover-missing-plan`** then **`generate-spec`** (templates, clarification loop, approval). Parallel batch rules per **`generate-spec`**. If **not** specs: complete step 2 with “no specs” rationale, then continue with steps 3–6 (still run official-doc pass when external surfaces change).
+  - **Pause →** Am I dodging specs just to avoid bureaucracy while scope is multi-team/critical?
+
+### 3) Authoritative docs
+
+- Official docs / Context7 / web for libs used in change.
+
+### 4) Implement
+
+- Minimal diffs preserving behavior unless tasked otherwise; specs ⇒ every in-scope unchecked item delivered; intermediate milestones ≠ user’s final asked outcome unless rescoped.
+
+### 5) Testing (always for non-trivial)
+
+- **`test-case-strategy`**: inventory risk → tests with oracles → run/fix.
+
+### 6) Completion
+
+- With specs: backfill **`spec.md`/`tasks.md`/`checklist.md`/`contract.md`/`design.md`** (+ **`coordination.md`** if batch truth moved). **`spec.md`** requirement status honest. Strip template noise / `N/A` properly.
+- Without specs: concise summary citing tests/results/`N/A` reasons.
+
+## Sample hints
+
+- **Spec yes**: Adds new permission model affecting API+DB+UI—the blast radius crosses layers.
+- **Spec no**: Off-by-one in existing pagination restoring documented behavior—fix + regression test.
+- **Split**: Touches auth, billing, infra—**three plans** capped modules, **`coordination.md`** collision map.
 
 ## References
 
-- `$generate-spec`: shared planning and approval workflow.
-- `$test-case-strategy`: shared test selection, oracle design, and unit drift-check workflow.
+- **`generate-spec`**: planning/backfill lifecycle
+- **`test-case-strategy`**: tests + drift philosophy
+- **`recover-missing-plan`**: heal missing dirs