ai-sdlc-doctor: Diagnostics And Safe Upgrade Plans

Internal AI SDLC skill, not client-facing by default. Doctor and upgrade planning are read-only with respect to installation files.

0. Skill Card

• Skill name:

  ai-sdlc-doctor

• Primary audience: Dev, Delivery
• Supporting audience: Release, Architecture
• Audience tags: Dev, Delivery, Release, Architecture
• SDLC stage: Installation and upgrade operations
• Purpose: Explain installation health and upgrade impact before mutation.
• Output:

  _ai_sdlc/doctor/report.{toon,json,md}

  or

  _ai_sdlc/upgrades/<id>/plan.{toon,json,md}

0.1 Required Inputs

• Repository root for doctor checks.
• Current and target versioned inventories plus active harness API for upgrade planning.

0.2 Clarification Rules

• Ask when the installation root or target inventory is ambiguous.
• Reject unsafe paths, invalid hashes, duplicate files, invalid versions, and incompatible API ranges.
• Never repair, install, delete, overwrite, migrate, or restore files automatically.

0.2.1 Flow Mode Flags

• Support

  --quick-flow

  and

  --full-flow

  ; full flow takes precedence.
• Full flow requires review of every warning, migration, backup, rollback, and blocker.

0.3 Output Rules

• Default to complete TOON with checks, evidence, remediation, file changes, migrations, backups, rollback actions, blockers, and fingerprints.
• Return summaries directly in the Codex response.
• Emit

  ai-sdlc-handoff/v1

  with

  result

  ,

  blockers

  ,

  next_required

  , and

  next_optional

  ; actions include

  reason

  ,

  command

  , and

  expected_artifact

  .
• Do not create

  summary.txt

  ,

  *-summary.txt

  , or another standalone summary file.

0.4 Artifact Routing

• Write generated reports only below repository

  _ai_sdlc/

  .
• Keep authored upgrade inventories visible and version controlled.
• Never treat a generated plan as authority to apply changes.

0.5 Feature State Machine

• Read owning feature

  _ai_sdlc/state.toon

  when diagnostics affect feature work.
• Diagnostics and upgrade plans do not mutate feature state.

0.6 Artifact Metadata And Metatags

• Related Markdown uses canonical

  artifact_metadata

  and

  metatags

  .
• Machine records use versioned doctor, inventory, and upgrade-plan schemas.

0.7 Specs Index

• Read

  _ai_sdlc/specs-index.toon

  first and use

  specs-index.md

  for human review.
• Operational reports do not refresh either index.

References

• Read

  references/doctor-contract.md

  before interpreting health or upgrade safety.
• Use

  references/diagnostics.json

  as the deterministic check registry.
• Validate inventories with

  references/upgrade-inventory.schema.json

  .
• Use

  scripts/doctor.py

  for all reports and plans.

Script Usage

python3 skills/ai-sdlc-doctor/scripts/doctor.py . --doctor --write
python3 skills/ai-sdlc-doctor/scripts/doctor.py . --upgrade --current current.json --target target.json --upgrade-id v2-preview --write

Purpose

Steps

1. Run registered prerequisite, layout, module, skill, and docs checks.
2. Report evidence and exact remediation without executing it.
3. Validate current and target inventories and API compatibility.
4. Diff files into add, modify, remove, unchanged, and schema-migration actions.
5. Plan backups for every modified or removed file.
6. Plan reverse-order rollback for every proposed change.
7. Emit TOON-first records; require a later authorized workflow to apply them.

Output Spec

Scope Boundary

• Do not install dependencies or modify the installation.
• Do not execute remediation, backup, migration, apply, or rollback actions.
• Do not hide incompatible or destructive changes behind an aggregate status.