feature-flow

name	feature-flow
description	Use when a feature or refactor changes public contracts, schemas, shared integration points, cross-layer data flow, release behavior, or other high-risk architecture decisions.

🌐 繁體中文（canonical） · English mirror

feature-flow — Harness high-risk-feature Profile

Core Principles

This skill supplies spec/design/implementation techniques and artifact templates for high-risk features. When Harness exists, Harness owns risk routing, state transitions, evidence, and contract lifecycle. This skill never creates a second state machine.

Without Harness, use the same profile after creating a risk assessment and one artifact root: docs/plans/<slug>/.

When to Use

Use for public APIs, schemas, shared integration points, cross-layer data flow, migrations, releases, auth/payments/production data, or features with both costly ambiguity and rollback.

Do not use merely because many files change. Low-risk mechanical changes use quick/standard. If design has no material tradeoff and no absolute escalation trigger, return to the risk router and downgrade.

Profile States

1. Discovery / Risk

Add Risk Assessment to plan.md: five signals, absolute triggers, matching contracts, reusable patterns, external side effects, and verification limits.

File count records blast radius but never selects the profile alone.

2. Spec

Create spec.md: Why, in/out scope, GIVEN-WHEN-THEN AC, assumptions, non-goals, and rollback conditions.

Ask the user only for costly ambiguity, product/scope tradeoffs, public contracts, irreversible actions, or external side effects. Decide reversible internals and record assumptions.

UI/UX ambiguity requires a mockup, walkthrough, or annotated screenshot before implementation.

3. Design / Plan

Create plan.md: architecture/data flow, Key Decisions, interfaces, migration/rollback, phases, phase acceptance, and planned evidence for every AC.

Every phase must be independently verifiable. Split phases that span unrelated risk surfaces. Prefer established adjacent patterns over generic design.

4. Implement

Before each phase, create a test/schema check/simulation/diff assertion that fails because the behavior is missing; then implement minimally. Red mechanical checks cannot transition.

When implementation disproves design, add a deviation record and revised evidence plan to plan.md. Never hide scope change or preserve a wrong design for document consistency.

5. Verify / Review

Record claim→evidence in evidence.md. Executable verification runs AC/build/test/baseline; semantic review checks requirements/contracts/architecture/scope; auth/data/release/irreversible surfaces add adversarial challenge.

The same model, prompt, and evidence path are not independent redundancy. Without a fresh reviewer, record "limited independence" and compensate with execution plus fresh read-back.

6. Close

Complete only when every required claim has evidence, no new baseline failure exists, and scope audit passes. review.md records residual risks, rollout/rollback, and omissions.

Put observations in contract-candidates.md; one observation remains candidate until repetition, explicit user ruling, or incident evidence promotes it.

Minimum Evidence

• Every AC: at least one test/command/read-back/manual item with source and result.
• Regression: compare to the opening baseline; do not merely say "green."
• Scope: map changed files to tasks; record unrelated existing bugs without fixing them.
• Release/device-only behavior: real-environment evidence; debug/simulator results are insufficient.

Failure Signals

• One design assumption fails twice → return to Design; stop adding exceptions.
• AC cannot be verified or achieved → return to Spec and ask for scope adjudication.
• One phase opens unrelated risk surfaces → return to Plan and split it.
• A reviewer offers opinion without an evidence gap or failure scenario → downgrade to suggestion.
• Both specs/changes/ and docs/plans/ receive process artifacts → stop; keep docs/plans/<slug>/ canonical.

Red Lines

• Push, merge, deploy, delete, or perform irreversible operations without explicit authorization.
• Substitute reviewer PASS, green CI, or checked boxes for functional evidence.
• Select this profile solely because 3+ files change.
• Promote a one-off preference directly to active contract.

References Index

File	Read when
references/artifact-templates.md	Creating spec.md, plan.md, evidence.md, review.md, or contract-candidates.md
references/lessons.md	Routing is unclear, review independence is weak, design is disproved, or ceremony costs too much