Maintenance

Maintenance (Production Maintenance Orchestrator)

> Purpose: Safely execute changes to a production system following a 5-stage ITIL-based workflow. > Automatically chains existing analysis skills (/impact, /deps, /coverage, /security-review, /changelog) > so the user does not need to run each one individually — the entire flow completes as a single operation. > > Core Principle: Production code is involved, so every change must follow impact analysis → user confirmation → modification → verification in that exact order.

---

Absolute Prohibitions

1. Do not modify code before completing the ASSESS stage
2. Do not proceed without user confirmation when risk is HIGH or CRITICAL
3. Do not move to the next file before running lint/type-check on the current one
4. Do not skip the VERIFY stage
5. Do not close the task without a change record (RECORD)

---

Prerequisites (auto-checked at skill start)

1. Git repository: A .git/ directory must exist. Halt if absent.
2. TASKS.md: Not required (production maintenance targets existing code).
3. Project type detection: Determine lint/test commands from package.json, pyproject.toml, Cargo.toml, etc.

---

5-Stage Workflow

/maintenance "request description"
    │
    ▼
[Stage 1: ASSESS]   Change classification + initial risk screening
    │
    ▼
[Stage 2: ANALYZE]  /impact + /deps + /architecture → impact report
    │                                                  ↓ HIGH/CRITICAL
    │                                           User confirmation required
    ▼
[Stage 3: IMPLEMENT] git branch + incremental changes + per-file validation
    │
    ▼
[Stage 4: VERIFY]   Tests + /coverage + /security-review
    │
    ▼
[Stage 5: RECORD]   Change record + commit + rollback plan

---

Stage 1: ASSESS (Change Acceptance Decision)

Analyze the user request and classify the change.

# 1. Identify target files
# Extract file names, function names, error messages, etc. from the user request

# 2. Classify change type
#   - Bug Fix: correct an existing behavior error
#   - Feature Change: alter the behavior of an existing feature
#   - Config Update: change configuration or environment variables
#   - Refactor: structural improvement without behavior change

# 3. Map to ITIL change type
#   - Standard: low risk, routine (config changes, text edits)
#   - Normal: medium risk, requires evaluation (logic changes, API edits)
#   - Emergency: incident response, immediate action (production down, security vulnerability)

Initial risk screening: Quickly determine risk from target file paths.

| Path Pattern | Risk Level | Reason | |---|---|---| | **/payment/**, **/billing/** | CRITICAL | Financial logic | | **/auth/**, **/security/** | CRITICAL | Authentication/security | | migrations/**, **/schema* | HIGH | Data structure | | **/api/**, **/routes/** | HIGH | External interface | | src/**, lib/** | MEDIUM | General business logic | | config/**, *.env* | MEDIUM | Environment config | | docs/**, *.md | LOW | Documentation | | tests/** | LOW | Test code |

Gate: Emergency displays a warning banner then proceeds. Normal + HIGH/CRITICAL requires user confirmation before proceeding.

---

Stage 2: ANALYZE (Impact Analysis)

Call existing analysis skills in order and consolidate impact.

1. /impact         → change impact + risk factors
2. /deps           → dependency graph + circular reference check
3. /architecture                → identify affected domains

Synthesize each skill's results into an impact report:

## Impact Report

| Item | Result |
|------|--------|
| Target files | 3 |
| Affected files | 12 |
| Affected domains | backend, api |
| Circular references | none |
| Risk level | HIGH |

### Risk Factors
- Core logic change in the payment domain
- Affects 3 API endpoints

Gate: If risk level is HIGH or CRITICAL, confirm with the user:

• Display impact summary
• Offer "Proceed / Reduce scope / Abort" choices

---

Stage 3: IMPLEMENT (Safe Modification)

Safely modify production code. All changes are made on a dedicated branch.

# 1. Create branch
git checkout -b maintenance/{change-type}-{short-description}

# 2. Incremental per-file modification
#    - Edit one file
#    - Immediately run lint + type-check
#    - On failure: git checkout --  to revert, then report to user
#    - On success: proceed to next file

# 3. Per-project validation commands
#    Node.js: npx eslint  && npx tsc --noEmit
#    Python:  ruff check  && mypy 
#    Rust:    cargo check

Principles:

• Modify only one file at a time
• Validate immediately after each modification — do not move to the next file before validating
• If all files fail validation, halt and suggest manual correction to the user

---

Stage 4: VERIFY (Test Reinforcement)

Validate the quality of modified code.

1. Run existing tests               → confirm all pass
2. /coverage         → check for coverage regression
3. /security-review --path   → check for security vulnerabilities

Validation verdict:

| Result | Verdict | Action | |--------|---------|--------| | All tests pass + coverage maintained + security clean | PASS | Proceed to RECORD | | Tests pass + coverage decreased | WARN | Show warning, user decides | | Tests fail | FAIL | Show failure cause, suggest fix | | CRITICAL security issue | BLOCK | Cannot proceed until security issue is resolved |

---

Stage 5: RECORD (Change History)

Systematically record the change history.

1. Update TASKS.md           → mark fixed tasks as [x], add new tasks if created
2. Create Change Record      → based on references/change-record-template.md
3. Write structured commit message
4. Present rollback plan

Commit message format:

{change-type}({domain}): {description}

Change-Type: {Standard|Normal|Emergency}
Risk-Level: {CRITICAL|HIGH|MEDIUM|LOW}
Impact: {affected domains}
Files: {count} modified
Rollback: git revert 

Rollback plan: After the commit, provide the rollback command to the user.

---

Final Report

After all stages complete, output a summary report:

┌─────────────────────────────────────────────┐
│  Maintenance Complete Report                 │
├─────────────────────────────────────────────┤
│ Change Type: Bug Fix (Normal)                │
│ Risk Level:  MEDIUM                          │
│                                              │
│ ✅ ASSESS:    Standard classification        │
│ ✅ ANALYZE:   3 files, 2 domains affected    │
│ ✅ IMPLEMENT: 3/3 files modified             │
│ ✅ VERIFY:    Tests pass, coverage maintained│
│ ✅ RECORD:    CR-20260316-001 created        │
│                                              │
│ Branch:   maintenance/fix-payment-null-check │
│ Rollback: git revert abc1234                 │
└─────────────────────────────────────────────┘

---

Skill Integration Table

| Stage | Called Skill | Purpose | |-------|-------------|---------| | ASSESS | (built-in logic) | Change classification + initial risk screening | | ANALYZE | /impact, /deps, /architecture | Consolidated impact analysis | | VERIFY | /coverage, /security-review | Quality + security validation | | RECORD | /changelog (auto via hook) | Change history record |

---

Reference Documents

• references/change-record-template.md — RFC-style change record template

---

Last Updated: 2026-03-16 (v1.0.0)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: insightflo
• Source: insightflo/claude-impl-tools
• License: MIT

Install and usage instructions live in the source repository linked above.