workflow-retrospective
Measure how the SDD workflow itself performed (rework cycles, blocked tasks, review tickets, quality-gate failures) and propose human-approved improvements to project workflow files.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- workflow-retrospective
- description
- Measure how the SDD workflow itself performed (rework cycles, blocked tasks, review tickets, quality-gate failures) and propose human-approved improvements to project workflow files.
- user-invocable
- false
- disable-model-invocation
- false
03 SKILL.md 正文
Workflow Retrospective
Observe and improve the SDD workflow process itself, not the application code.
Invocation
Codex:
Use the workflow-retrospective skill for specs/<feature>
Claude Code — internal skill, not directly invocable. Reached by following this file from its entry command:
/sdd-ship:ship --retro specs/<feature>/tasks.md
Metrics Collection (read-only)
Read the following sources; do not modify them:
reports/implementation/— one report per task cyclereports/quality-gate/— one report per quality-gate rundocs/review-tickets/— all YAML tickets for the featuregit log --oneline— commit history scoped to the feature pathreports/spec-review/— spec-review-contract.json files for each featurereports/task-review/— task-review-contract.json files for each featurereports/impl-review/— impl-review-contract.json files for each feature- previous
reports/retrospective/*.md— comparison baseline and prior WFI verification results reports/runs/RUN-*.json— machine-readable run records from prior runs (attribution baseline for WFI verification)docs/workflow-improvements/WFI-*.md— Applied WFIs with open verification horizonsdocs/workflow-improvements/retention-checklist.md— recurrence conditions for previously Verified WFIs
For each task derive:
- QG Cycles — count of quality-gate reports for that task
- Task Attempts — read
Task Attempt Countfrom the latest current-schema implementation report for the task. - Review Rounds — count independent review rounds recorded for the task across its implementation and review evidence.
- Quality-Gate Runs — count quality-gate reports for the task, including failed and blocked runs rather than only the final passing run.
- Model Escalations — count complete escalation transitions whose prior tier, next tier, failure class, attempt number, and reason are all recorded.
- Blocked Count — count of
Blockeddecisions across those reports - Tickets — count of review tickets by severity (
critical,major,minor) - Auto-fixed — count of tickets where
auto_fix_allowed: trueandstatus: resolved - Outcome — final task status (
Doneor still open)
Legacy implementation reports without these additive fields contribute N/A;
do not infer or fabricate missing attempt, review-round, or escalation values.
Deterministic artifact rules
Apply these rules before calculating the table. All paths below are canonical
repository-relative paths, and <feature> and T-NNN must exactly match the
requested feature and task:
- Implementation attempts. The authoritative candidates are
reports/implementation/<feature>/T-NNN.mdandreports/implementation/<feature>/T-NNN-attempt-<positive integer>.md. The report heading task ID and itsRun IDmust agree with the path and be non-empty. De-duplicate candidates with the same(task ID, Run ID)by retaining the lexicographically smallest canonical path. Select the current task report by the greatest numericTask Attempt Count; break a tie by the lexicographically greatestRun ID, then the lexicographically smallest canonical path. The selected report supplies the cumulative Task Attempts value. Schema-less legacy candidates sort below current-schema candidates and contributeN/Aonly when no current-schema candidate remains. - Independent review rounds. The authoritative artifacts are
reports/implementation/<feature>/T-NNN-review-<positive integer>.md. Associate by the path task ID and require the report'sTaskidentity to match. The suffix is the round number. De-duplicate on(task ID, round number)by retaining the lexicographically smallest canonical path, then count the retained rounds in numeric round order. - Quality-gate runs. The authoritative artifacts are Markdown files under
reports/quality-gate/with exactly one task-identity line — the canonicalTask ID: T-NNN(quality-report template, WFI-020), or the legacyTask: T-NNNform in reports that predate it — and one non-emptyRun ID. Associate only by that exact task identity. De-duplicate on(task ID, Run ID)by retaining the lexicographically smallest canonical path. Count retained reports, including PASS, FAIL, and BLOCKED, ordered byRun IDand then canonical path. - Model escalations. Read complete transition records from the retained
implementation, independent-review, and quality-gate artifacts. Associate
each record with the artifact's validated task identity. De-duplicate the
same transition across evidence sources on
(task ID, escalation attempt number, prior tier, next tier, failure class). Retain the record from the lexicographically smallest canonical path and order by numeric escalation attempt, prior tier, next tier, failure class, then path. Conflicting reasons for one de-duplication key make Data CompletenessBlocked; do not choose or count either conflicting record. - Invalid or ambiguous evidence. A candidate with a mismatched identity, malformed positive integer, duplicate identity with conflicting metric values, or missing required association field is excluded and recorded in the report's data-completeness explanation. Such evidence must never be repaired from filenames, timestamps, chat history, or filesystem iteration order.
Also derive dataset quality indicators:
- Sample Size — number of tasks, review contracts, quality-gate reports, and review tickets used.
- Data Completeness — Complete when all expected report roots exist for the feature; Partial when an optional source is missing; Blocked when required task or quality-gate evidence is absent.
- Confidence — High for recurring patterns across at least three tasks or two independent evidence types; Medium for recurring patterns across two tasks; Low for single-task observations. Low-confidence observations may be reported but must not create a WFI.
Domain-drift metrics (when domain/ exists)
When the project carries a domain/ directory, extend the metric roll-up
with domain-drift counts sourced only from check-domain-conformance
findings already recorded in reports/quality-gate/*.md (the retained
reports selected by rule 3 above). Do not re-run check-domain-conformance
and do not read domain/ artifacts directly — this is a read-only rollup
over already-recorded quality-gate text, not a new evidence-collection path.
When domain/ is absent, skip this subsection entirely and omit the Domain
Drift Metrics table from the report (do not emit a zero-filled table).
- Within each retained quality-gate report's text, locate every
check-domain-conformance WARN (<n> finding(s)):orcheck-domain-conformance FAILED (<n> finding(s)):block (the exact output format produced byplugins/sdd-quality-loop/scripts/check-domain-conformance.{sh,ps1}) and collect its- <finding text>lines. - Classify each finding line by matching its text against the fixed set of
messages the script can produce:
- Term deviation — lines matching
unrecognized term '...', oraggregate reference '...' not found in domain-contract.json aggregates, oraggregate reference '...' has no domain/aggregates/ ....md card. These all report a name/vocabulary the domain contract does not recognize. - Boundary violation — lines matching
Bounded-Context '...' not found in domain-contract.json, orBounded-Context lists two contexts (...) with no declared relation in context map. These report an undeclared context or an undeclared cross-context relation (AC-015). - A line matching neither pattern (e.g. a
requirements.md not found: .../design.md not found: ...input error) is not a drift finding; do not count it in either bucket.
- Term deviation — lines matching
- Term-Deviation Count — total term-deviation finding lines across all retained quality-gate reports for the feature in this period.
- Boundary-Violation Count — total boundary-violation finding lines across the same reports.
- Domain-Drift Trend — compare this period's combined
(Term-Deviation Count + Boundary-Violation Count) against the previous
retrospective's combined total (from its Domain Drift Metrics table, when
one exists). Report
N/Awhen no previous retrospective recorded this metric. A sustained increase across two or more consecutive retrospectives is a friction pattern candidate under the Improvement Loop (Section 1), subject to the same two-task recurrence and confidence rules as any other friction pattern — never draft a WFI from a single period's counts alone.
De-duplicate on the same (task ID, Run ID) quality-gate report selection
already established in rule 3 of the Deterministic artifact rules above; a
report excluded there (e.g. a duplicate Run ID) does not contribute
domain-drift findings either.
For spec-review, task-review, and impl-review metrics, scan the contract files and derive:
-
spec_review_rounds_per_feature — for each feature, the round number of the final passing spec-review-contract.json (rounds consumed to reach PASS). If no PASS contract exists, record the maximum round reached.
-
spec_review_blocked_rate — percentage of features where the spec-review-loop reached BLOCKED state (verdict == BLOCKED in the final attempt's last round).
-
task_review_rounds_per_feature — for each feature, the round number of the final passing task-review-contract.json (rounds consumed to reach PASS). If no PASS contract exists, record the maximum round reached.
-
task_review_blocked_rate — percentage of features where the task-review-loop reached BLOCKED state (verdict == BLOCKED in the final attempt's last round).
-
impl_review_rounds_per_feature — for each feature, the round number of the final passing impl-review-contract.json.
-
impl_review_blocked_rate — percentage of features where the impl-review-loop reached BLOCKED state.
-
impl_review_legacy_design_rate — percentage of features where
legacy_design: truein at least one impl-review-contract.json.
Applied-WFI Verification (horizon and retention)
Run these two checks on every retrospective, before drafting any new WFI. They are what makes self-improvement measurable instead of impressionistic: never classify a WFI from the feeling that "the run went smoother" — only from run records and report counts.
Horizon check. For every WFI with Status: Applied:
- Read its
Verification Metricblock (Target-Metric,Expected-Direction,Horizon,Baseline,Target). - Compare the baseline against the current run records (
reports/runs/) and this retrospective's metrics. Report counts, not percentages, when fewer than 20 runs exist. - Classify:
- Target met → set
Status: Verified, append the comparison to## Result, and add the WFI's recurrence condition todocs/workflow-improvements/retention-checklist.md. - Direction improved, target unmet, horizon still open → leave Applied and
record
Needs-Followupin## Result. - Horizon expired without the target being met, or the metric worsened →
set
Status: Rejected, append the evidence to## Result, and present the WFI'sRollback-Planto the human for approval. Do not execute the rollback without human approval.
- Target met → set
Retention check. Read docs/workflow-improvements/retention-checklist.md
(if absent, skip and note that in the report). For each entry, check whether the
recurrence condition matches any evidence in this period. On recurrence:
set the source WFI's Status: Regressed, record the evidence in its
## Result, remove the checklist entry, and treat the recurrence as a friction
pattern candidate for a follow-up WFI. Retention answers the question most
loops forget: do previously fixed failure modes stay fixed?
Before crediting or blaming any WFI, read the transcripts or reports behind the changed metric: grading artifacts can masquerade as effects.
Output
Generate reports/retrospective/<timestamp>.md using the structure below.
Fill every section; do not leave any {{}} field blank.
# Retrospective Report
## Header
| Field | Value |
|---|---|
| Feature | {{feature}} |
| Period | {{period_start}} – {{period_end}} |
| Generated | {{generated_timestamp}} |
| Sample Size | {{task_count}} tasks, {{review_contract_count}} review contracts, {{qg_report_count}} QG reports, {{ticket_count}} tickets |
| Data Completeness | {{complete_partial_blocked}} |
| Confidence | {{high_medium_low_with_reason}} |
## Metrics
| Task | Task Attempts | Review Rounds | Quality-Gate Runs | Model Escalations | Blocked Count | Tickets (C/M/Min) | Outcome |
|---|---|---|---|---|---|---|---|
| {{task_id}} | {{task_attempts}} | {{review_rounds}} | {{quality_gate_runs}} | {{model_escalations}} | {{blocked_count}} | {{critical}}/{{major}}/{{minor}} | {{outcome}} |
| **Total** | | | | | | | |
_C = Critical, M = Major, Min = Minor_
## Domain Drift Metrics
_Include this section only when `domain/` exists; omit entirely otherwise._
| Metric | This Period | Previous Period | Trend |
|---|---|---|---|
| Term-Deviation Count | {{term_deviation_count}} | {{prev_term_deviation_count}} | {{trend}} |
| Boundary-Violation Count | {{boundary_violation_count}} | {{prev_boundary_violation_count}} | {{trend}} |
| Combined Domain-Drift Count | {{combined_drift_count}} | {{prev_combined_drift_count}} | {{trend}} |
Counts are sourced only from `check-domain-conformance` findings already
recorded in the retained `reports/quality-gate/*.md` reports for this
feature; see the Domain-drift metrics rules above. A sustained increase
across two or more consecutive retrospectives is a friction-pattern
candidate (see Friction Patterns / Improvement Loop below), not an automatic
WFI trigger.
## Friction Patterns
Patterns observed across two or more tasks in this period.
### {{pattern_id}}: {{pattern_title}}
- **Evidence:** {{affected_tasks_and_ticket_ids}}
- **Frequency:** {{occurrence_count}} occurrences
- **Phase:** {{workflow_phase}}
- **Confidence:** {{high_medium_low}}
- **Do Not Overfit:** {{why_this_is_not_a_single_task_exception}}
## Proposed Improvements
| WFI-ID | Status | Problem | Target File(s) |
|---|---|---|---|
| {{wfi_id}} | Draft | {{problem_summary}} | {{target_files}} |
## Improvement Verification Plan
| WFI-ID | Expected Effect Metric | Baseline | Target | Next Checkpoint |
|---|---|---|---|---|
| {{wfi_id}} | {{metric}} | {{baseline}} | {{target}} | {{next_feature_or_date}} |
## Review Gate Metrics
| Feature | Spec Review Rounds | Spec Review Verdict | Task Review Rounds | Task Review Verdict | Impl Review Rounds | Impl Review Verdict | Legacy Design |
|---|---|---|---|---|---|---|---|
| {{feature}} | {{spec_review_rounds}} | {{spec_review_verdict}} | {{task_review_rounds}} | {{task_review_verdict}} | {{impl_review_rounds}} | {{impl_review_verdict}} | {{legacy_design}} |
## Comparison With Previous Retrospective
| Metric | Previous | This Period | Trend |
|---|---|---|---|
| Avg QG Cycles per Task | {{prev_avg_qg}} | {{curr_avg_qg}} | {{trend}} |
| Avg Task Attempts | {{prev_task_attempts}} | {{curr_task_attempts}} | {{trend}} |
| Avg Review Rounds | {{prev_review_rounds}} | {{curr_review_rounds}} | {{trend}} |
| Avg Quality-Gate Runs | {{prev_quality_gate_runs}} | {{curr_quality_gate_runs}} | {{trend}} |
| Total Model Escalations | {{prev_model_escalations}} | {{curr_model_escalations}} | {{trend}} |
| Total Blocked Count | {{prev_blocked}} | {{curr_blocked}} | {{trend}} |
| Total Review Tickets | {{prev_tickets}} | {{curr_tickets}} | {{trend}} |
| Auto-fix Rate | {{prev_autofix_pct}} | {{curr_autofix_pct}} | {{trend}} |
| Avg Spec Review Rounds | {{prev_spec_review_rounds}} | {{curr_spec_review_rounds}} | {{trend}} |
| Spec Review Blocked Rate | {{prev_spec_review_blocked}} | {{curr_spec_review_blocked}} | {{trend}} |
| Avg Task Review Rounds | {{prev_task_review_rounds}} | {{curr_task_review_rounds}} | {{trend}} |
| Task Review Blocked Rate | {{prev_task_review_blocked}} | {{curr_task_review_blocked}} | {{trend}} |
| Avg Impl Review Rounds | {{prev_impl_review_rounds}} | {{curr_impl_review_rounds}} | {{trend}} |
| Impl Review Blocked Rate | {{prev_impl_review_blocked}} | {{curr_impl_review_blocked}} | {{trend}} |
| Impl Legacy Design Rate | {{prev_legacy_design_rate}} | {{curr_legacy_design_rate}} | {{trend}} |
| Repeat Finding Rate | {{prev_repeat_finding_rate}} | {{curr_repeat_finding_rate}} | {{trend}} |
| WFI Verification Rate | {{prev_wfi_verification_rate}} | {{curr_wfi_verification_rate}} | {{trend}} |
_If no previous retrospective exists, mark all "Previous" cells as N/A._
## Applied WFI Horizon Check
| WFI-ID | Target-Metric | Baseline | Target | Current | Horizon | Classification |
|---|---|---|---|---|---|---|
| {{wfi_id}} | {{target_metric}} | {{baseline}} | {{target}} | {{current}} | {{horizon}} | {{verified_needs_followup_rejected}} |
_List every WFI that was `Status: Applied` at the start of this retrospective.
If none, state "No applied WFIs with open horizons."_
## Retention Check
| Source WFI | Recurrence Condition | Recurred? | Evidence |
|---|---|---|---|
| {{wfi_id}} | {{condition}} | {{yes_no}} | {{evidence_or_dash}} |
_One row per entry in retention-checklist.md. If the checklist is absent or
empty, state that explicitly._
Run Record (machine-readable)
After writing the retrospective report, emit the machine-readable run record:
scripts/emit-run-record.sh <feature> --track <full|lite> \
--model-main <model id used for implementation> \
--model-reviewers <model id used for review agents> \
--plugin-version <installed sdd plugin version>
(or emit-run-record.ps1 with the equivalent named parameters; if the project
has no scripts/ copy, run it from the installed sdd-quality-loop plugin's
scripts/ directory).
The script deterministically counts tasks, first-try gate passes, gate reports, blocked reports, and review tickets, and records the currently Applied WFIs — do not compute these numbers yourself and do not edit the emitted JSON. Pass the model ids and track as arguments; they are per-run confound metadata that future attribution analysis cannot recover after the fact. If a model version changed since the previous run record, note that in the retrospective report: metric shifts across a model change must not be attributed to WFIs.
Improvement Loop
-
Identify friction. Flag patterns that recur across at least two tasks:
- Same
typeof review ticket appears repeatedly. - A phase produces
Blockedmore than once. - Auto-fix rate drops below 50 % for a ticket type.
- A prior WFI's expected-effect metric does not improve by its next checkpoint.
Do not draft a WFI from a single-task observation. Record it under Friction Patterns with Low confidence only when it may become relevant later.
- Same
1.5. Classify the WFI. Before drafting, walk the Section 1 flowchart of
plugins/sdd-quality-loop/references/wfi-category-guide.md to set the
scope axis (Category), then set the mechanism axis (Mechanism) from
Section 5:
measurement(checked first): the change touches graders, gate thresholds, retrospective/audit logic, or run-record definitions. ForcesMeta-Change: trueand the strict audit lane (category guide Section 5).human-process: the change alters approval policy, escalation rules, or what humans review.plugin-improvement: friction evidence comes from the "Review Gate Metrics" table (spec_review_rounds,spec_review_blocked_rate,impl_review_rounds,task_review_blocked_rate,impl_review_blocked_rate,impl_review_legacy_design_rate) or involves cross-plugin handoff transitions (design review → task decomposition → implementation flow). These WFIs are expressed in generic workflow terms (see Section 2 of the category guide) and will be tracked as GitHub Issues.app-dev-efficiency: all other friction patterns (task sizing, test coverage gaps, spec quality, project-specific recurring ticket types). These WFIs use project-specific concrete language (feature slugs, task IDs, RT-IDs).
Mechanism is one of instructions | memory | tools | architecture | model-routing. Set Meta-Change: true whenever the proposed change touches
anything that measures the workflow, regardless of Category.
For plugin-improvement WFIs: read Section 2 of wfi-category-guide.md and
apply all term substitutions to Root Cause Hypothesis, Proposed Change, and
Expected Effect. Problem Evidence may cite raw metric names from the retrospective.
1.75. Run the why-why analysis (なぜなぜ分析). Before writing any Root Cause Hypothesis, walk a 5-Whys chain from the observed friction down to a root cause the Proposed Change can actually fix:
- Row 1 asks why the friction from Problem Evidence occurred; each subsequent row asks why the previous row's answer occurred (chain rule).
- Go at least 3 levels deep, 5 when the chain supports it. Stop only when the answer names a controllable process or mechanism cause — never at a restated symptom, at "human/agent error", or at a cause outside the workflow's control. Do not pad the chain past the root cause just to reach 5 rows.
- Back each row with evidence (retrospective table row, RT-ID, BL-ID,
report path, or file:line). Mark rows you cannot corroborate as
(hypothesis). - The final row's answer becomes the
## Root Cause Hypothesis, and the## Proposed Changemust act on that terminal cause — if the change only treats an intermediate "why", either deepen the change or shorten the chain to what the evidence supports.
Record the chain in the WFI's ## Why-Why Analysis section (structure
below). The audit cycle rejects chains that restate symptoms, skip links,
or terminate at blame instead of mechanism (WHY-CHAIN-VALID check).
-
Draft a WFI. For each identified friction, create
docs/workflow-improvements/WFI-NNN.mdwithStatus: Draftusing the structure below. Increment NNN from the highest existing WFI number (start at 001 if none exist). If the repository also runs an automated self-improvement routine (e.g. it has.github/self-improvement-prompt.md), check open issues labeledself-improvementfirst; if one covers the same theme, reference its issue number in the WFI instead of duplicating the work.# Workflow Improvement ## WFI-ID {{wfi_id}} ## Status Status: Draft <!-- Allowed values: Draft | Approved | Applied | Verified | Rejected | Regressed --> <!-- Only a human may set status to Approved. The AI sets Draft, Applied, --> <!-- Verified, Rejected, and Regressed. --> ## Category Category: {{plugin-improvement|app-dev-efficiency|human-process|measurement}} <!-- Scope axis — walk wfi-category-guide.md §1 flowchart. --> <!-- plugin-improvement: use generic workflow terms (wfi-category-guide.md §2). --> <!-- app-dev-efficiency: use project-specific detail (feature slug, task IDs). --> <!-- measurement: forces Meta-Change: true (strict audit lane, guide §5). --> ## Mechanism Mechanism: {{instructions|memory|tools|architecture|model-routing}} <!-- Mechanism axis — what kind of thing changes (wfi-category-guide.md §5). --> ## Meta-Change Meta-Change: {{true|false}} <!-- true when the change touches graders, thresholds, retrospective/audit --> <!-- logic, or run-record definitions (wfi-category-guide.md §5). --> ## GitHub-Issue GitHub-Issue: {{N/A for app-dev-efficiency | Pending for plugin-improvement}} <!-- Populated by wfi-audit-cycle after gh issue create (plugin-improvement only). --> ## Audit-Status Audit-Status: Not-Started <!-- wfi-audit-cycle advances this through Cycle-1-In-Progress → --> <!-- Cycle-2-In-Progress → Human-Pending before human review. --> ## Problem Evidence {{metrics_and_ticket_references}} <!-- Quote specific BL-IDs, RT-IDs, or retrospective table rows that show the friction. --> <!-- For plugin-improvement: raw metric field names are acceptable here. --> ## Why-Why Analysis | # | Why (question) | Because (answer) | Evidence | |---|---|---|---| | 1 | Why did {{observed_friction}} occur? | {{because_1}} | {{evidence_ref_1}} | | 2 | Why did {{because_1}} occur? | {{because_2}} | {{evidence_ref_2}} | | 3 | Why did {{because_2}} occur? | {{because_3}} | {{evidence_ref_3}} | <!-- 5-Whys chain from step 1.75. At least 3 levels; each Because is the --> <!-- next row's Why subject; final Because = Root Cause Hypothesis mechanism. --> <!-- Never terminate at a restated symptom, "human/agent error", or an --> <!-- uncontrollable cause. Cite evidence per row; mark unproven rows --> <!-- "(hypothesis)". Why/Because prose follows the category language rules; --> <!-- the Evidence column may cite raw metric names like Problem Evidence. --> ## Root Cause Hypothesis {{root_cause}} <!-- Must be the terminal cause of the ## Why-Why Analysis chain. --> <!-- plugin-improvement: use generic workflow terms only (wfi-category-guide.md §2). --> <!-- app-dev-efficiency: name the specific feature/task/ticket driving the issue. --> ## Proposed Change | Target File | Change Description | |---|---| | {{file_path}} | {{change_description}} | <!-- Target files must be project-side workflow files only (AGENTS.md, CLAUDE.md, --> <!-- specs/ templates, task-splitting guidelines). Plugin files must not be listed. --> ## Expected Effect {{expected_effect}} <!-- State the metric(s) expected to improve and by how much. --> <!-- plugin-improvement: use generic metric names from wfi-category-guide.md §2. --> <!-- app-dev-efficiency: use project-specific metric names with concrete targets. --> ## Verification Metric Target-Metric: {{run_record_metric_key}} Expected-Direction: {{increase|decrease}} Horizon: {{within_next_N_runs_or_date}} Baseline: {{baseline_count}} Target: {{target_count}} <!-- Target-Metric names one run-record key (reports/runs/RUN-*.json) or a --> <!-- retrospective table column. Horizon is binding: expiry without the target --> <!-- met → Status: Rejected + rollback proposal. Use counts, not percentages. --> ## Verification Plan {{verification_plan}} <!-- Describe how the next task cycle will confirm the improvement. --> <!-- Reference the specific metric rows from the retrospective template. --> ## Rollback-Plan {{rollback_plan}} <!-- Exact files/sections changed and how to revert (normally: git revert of --> <!-- the commit whose message contains this WFI-ID). Required before Approved. --> ## Result Pending <!-- Fill after the next task cycle completes. Append a comparison table. -->
2.5. Trigger audit cycle. Immediately after creating the WFI Draft, invoke
the wfi-audit-cycle skill for every new WFI regardless of category:
Claude Code:
/sdd-quality-loop:wfi-audit-cycle WFI-NNN
Codex:
Use the wfi-audit-cycle skill for WFI-NNN
The audit cycle runs 2 independent review cycles (Cycle 1: proposal quality;
Cycle 2: impact and risk), revises the WFI between cycles, and sets
Audit-Status: Human-Pending when complete.
For plugin-improvement WFIs, wfi-audit-cycle also creates a GitHub Issue
after both cycles complete.
Record the WFI in the retrospective report under "Proposed Improvements" only
after the audit cycle completes (i.e., after Audit-Status: Human-Pending is
set). Use these status labels in the table:
| Category | Status label in table |
|---|---|
plugin-improvement |
Human-Pending (audited, issue created) |
app-dev-efficiency |
Human-Pending (audited) |
-
Await human Approved. Do not apply any improvement until a human sets the WFI
statustoApproved. Record the pending WFI references in the retrospective report under "Proposed Improvements". -
Apply approved improvements. Modify only project-side workflow files:
AGENTS.mdorCLAUDE.mdin the project rootspecs/template files or task-splitting guidelines- Task granularity guidance documents
Do not modify installed plugin files (skills, references, templates inside
plugins/).Always include the WFI ID (
WFI-NNN) in the commit message and any PR that applies an approved improvement. Automated maintenance routines treatWFI--referenced changes as protected and will not revert them; changes without the marker lose that protection. The WFI-ID-in-commit rule is also what makes theRollback-Planexecutable: reverting the WFI is reverting that commit.Adoption hygiene (attribution discipline): apply at most one WFI (or one explicitly labeled batch) per verification window, and never mid-run. Simultaneous unlabeled adoptions make it impossible to attribute a metric shift to any single change.
-
Verify effect. After the next task cycle completes, re-run metrics collection (the Applied-WFI Verification section above) and append a
Resultsection to the WFI document. Compare theVerification Metricbaseline and target with the current run records. Classify the result as:Verified: target met without introducing a worse repeated friction. Register the recurrence condition indocs/workflow-improvements/retention-checklist.md.Needs-Followup: direction improved but target was not met and the horizon is still open.Rejected: metric worsened, the horizon expired without the target, or the proposal caused a new repeated failure. Present theRollback-Planto the human.Regressed(set by the retention check, possibly many cycles later): a previously Verified WFI's failure mode recurred.
This mirrors continuous eval practice: keep the successful regression signal, promote recurring misses into new WFI candidates, and avoid reactive changes from one-off failures. A model-version change between baseline and checkpoint invalidates the comparison — note it and extend the horizon instead of classifying.
Sudo Mode
A valid SDD_SUDO flag does not bypass WFI approval. Setting a WFI status
to Approved changes the SDD workflow itself (governance), so it remains a
human-only action even under sudo: continue to await human Approved before
applying any improvement. The WFI records status as an inline Status: <value>
field; a hook guard denies any agent edit introducing Status: Approved in a
docs/workflow-improvements/WFI-*.md file, and is never bypassed by sudo.
Read-only metrics collection runs as normal. See
plugins/sdd-quality-loop/references/sudo-mode-policy.md.
Boundaries
- Do not modify application code.
- Do not change task status fields.
- Do not commit or push unless the human explicitly requests it.
- Do not create, resolve, or modify review tickets.
- Do not invoke
quality-gateorfix-by-review-ticket.
04 同仓库更多 Skills
status
Show a read-only Jira-style six-view SDD dashboard in the initiating parent's Sites or Claude Artifacts, with source freshness and failure visibility.
verify-review-reservation
Recheck the bounded identity-ledger reservation invariant after lock, hash-check or publication changes.
aws-cdk
Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Applies when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
quality-gate
Independently verify an Implementation Complete task with a Default-FAIL verification contract, deterministic checks, and an isolated critical reviewer, then decide whether it is Done.
ship
Implement approved SDD tasks through the quality gate to Done — the second of the two-command workflow. Run after /sdd-bootstrap:bootstrap and human task approval.
ship
Implement approved SDD tasks through the quality gate to Done — the second of the two-command workflow. Run after /sdd-bootstrap:bootstrap and human task approval.