ai-sdlc-doctor

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

Make operational gaps and upgrade risk reviewable before any installation mutation.

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

Doctor checks have stable codes, statuses, evidence, and remediation. Upgrade plans contain exact hashes, schema transitions, backup destinations, rollback actions, compatibility blockers, and deterministic identity.

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.