ai-sdlc-change-impact: Evidence-Backed Lifecycle Recovery

Internal AI SDLC skill, not client-facing by default. Every rule below is important to follow. None of it can be skipped. Analysis proposes recovery actions; the owning lifecycle skill applies them.

0. Skill Card

• Skill name:

  ai-sdlc-change-impact

• Primary audience: Delivery, Dev, BA, QA
• Supporting audience: PM, Architecture, Security
• Audience tags: Delivery, Dev, BA, QA
• SDLC stage: Cross-lifecycle change recovery
• Purpose: Trace changed sources to stale artifacts and safe reopen actions.
• Output:

  change-impact.md

  and

  _ai_sdlc/change-impact.toon

0.1 Required Inputs

• Feature root in

  specs/

  or

  specs-refiniment/

  .
• A JSON change set with stable changed references and exact source evidence.
• Readable feature artifacts and, in full flow, canonical lifecycle state.

0.2 Clarification Rules

• Ask only when the feature, changed reference, or source evidence is ambiguous.
• Do not infer that an artifact is stale without an exact trace occurrence.
• Report missing state or unowned artifacts as blockers, not guessed stages.
• Preserve multiple changes independently even when they affect one artifact.

0.2.1 Flow Mode Flags

• Support

  --quick-flow

  and

  --full-flow

  ; full flow takes precedence.
• Quick flow scans feature Markdown and reports missing state as a blocker.
• Full flow requires canonical state plus valid changed-reference source lines.
• Neither mode changes state, artifacts, decisions, tasks, or indexes.

0.3 Output Rules

• Return changed refs, stale artifacts, affected stages, blockers, and ordered reopen actions directly in the Codex response.
• Before the final response, emit

  ai-sdlc-handoff/v1

  with

  result

  ,

  blockers

  ,

  next_required

  , and

  next_optional

  ; every action includes

  reason

  ,

  command

  , and

  expected_artifact

  .
• Do not create

  summary.txt

  ,

  *-summary.txt

  , or ad hoc recovery files.
• Every affected artifact and reopen action must retain exact evidence.

0.4 Artifact Routing

• Write human analysis to

  <feature-root>/change-impact.md

  .
• Write machine analysis to

  <feature-root>/_ai_sdlc/change-impact.toon

  .
• Never overwrite the changed source, downstream artifacts, or state.
• Route approved actions through the owning lifecycle skill.

0.5 Feature State Machine

• Read

  <feature-root>/_ai_sdlc/state.toon

  before proposing stage actions.

• --state-check

  validates read-only state availability.

• --begin-state

  and

  --complete-state

  are rejected because analysis cannot authorize reopening.
• A

  reopen

  proposal applies only to a stage currently in a complete state; active and not-started stages receive revalidation or pre-start gates.
• The owning workflow records accepted recovery in state and decision log.

0.6 Artifact Metadata And Metatags

• Markdown starts with

  artifact_metadata

  using schema

  ai-sdlc-change-impact-metadata/v1

  .
• Include

  metatags

  for

  ai-sdlc

  ,

  change-impact

  ,

  recovery

  , and the affected stage identifiers.
• Record feature, workspace, changed refs, state file, and flow mode.

0.7 Specs Index

• Read

  specs/_ai_sdlc/specs-index.toon

  or

  specs-refiniment/_ai_sdlc/specs-index.toon

  before feature analysis.
• Do not refresh

  specs/specs-index.md

  or

  specs-refiniment/specs-index.md

  during read-only analysis.
• The owning workflow refreshes indexes only after an accepted state or authoritative artifact change.

References

• Read

  references/change-set-contract.md

  before preparing change evidence.
• Use

  scripts/change_impact.py

  for deterministic trace scanning, stage mapping, validation, and canonical report generation.

Script Usage

python3 skills/ai-sdlc-change-impact/scripts/change_impact.py specs/payments --changes /tmp/changes.json --emit --quick-flow
python3 skills/ai-sdlc-change-impact/scripts/change_impact.py specs/payments --changes /tmp/changes.json --write --full-flow --format toon
python3 skills/ai-sdlc-change-impact/scripts/change_impact.py specs/payments --changes /tmp/changes.json --state-check --format toon

--write

Purpose

Inputs

• Use repository-relative source evidence with a positive line number.
• Use stable trace IDs already present in source and downstream artifacts.
• Read state status and artifact ownership from canonical repository records.
• Exclude generated change-impact reports from their own analysis.

Steps

1. Record each changed reference and exact changed-source evidence.
2. Validate that the source path is inside the feature and the evidence line contains the changed reference.
3. Scan feature Markdown for exact downstream trace occurrences.
4. Map affected artifacts to lifecycle skills and stages using metadata.
5. Classify the safe action from current state: reopen complete work, revalidate active work, or add a pre-start validation gate.
6. Order actions by canonical lifecycle stage order and retain all evidence.
7. Emit or write the analysis, then hand approved actions to owning skills.

Output Spec

ai-sdlc-change-impact/v1

stage

skill

action

reason

evidence_path

evidence_line

changed_ref

expected_artifact

• Pass when every change has valid source evidence and every impact/action is backed by an exact downstream trace occurrence.
• Full flow fails when state is absent, source evidence is invalid, or an affected artifact cannot be mapped to a lifecycle owner.

Examples

{"id":"CHG-001","changed_ref":"AC-004","source":{"path":"requirements.md","line":121,"detail":"Retry behavior changed from optional to required."}}

The requirements changed recently.

Edge Cases

• A valid change with no downstream occurrence reports no stale artifact and recommends targeted trace review rather than broad reopening.
• Multiple occurrences in one artifact are collapsed into one affected row per changed reference using the earliest exact line as evidence.
• Unknown artifact owners block full flow but remain visible in quick flow.
• Already active stages are revalidated, never reopened concurrently.

Scope Boundary

• Do not mutate lifecycle state, indexes, source artifacts, or policy.
• Do not reopen a stage solely because it follows another stage chronologically.
• Do not treat filename similarity or model intuition as impact evidence.
• Do not approve recovery actions on behalf of artifact owners.
• Use

  $ai-sdlc-navigator

  when the owning workflow is unclear.