Skip to content

skill · phase: maintenance

Maintenance Phase

Purpose

Ensure the deployed feature remains healthy. Update documentation, address feedback, and plan follow-up work.

Entry Criteria

{{glossary:instance}}

  • Deployment phase complete
  • The instance is claimed by this session

Entering in a fresh session

Always start maintenance in a fresh session. At 791k tokens per unit of work it is by a wide margin the most expensive phase to run, and it is open-ended — so a carried prefix here is not paid once but on every turn for as long as the instance stays open.

Read only:

  • instance.yaml
  • deployment-record.md — what shipped, and what was deferred
  • whatever the specific maintenance question sends you to

Nothing from before deployment by default. See The context rule in aidlc-overview.

Required Artifacts

The artifacts your template's maintenance phase declares in required_artifacts — maintenance-plan.md for full-feature. Read phase-maintenance.yaml in the instance state dir if unsure. Whatever the filename, the content is post-deployment notes, monitoring status, known issues, and follow-up items.

Instructions

  1. Load guidance. Read the always-read guidance layers from .aidlc/guidance/index.yaml — see The always-read rule in aidlc-overview for which layers those are and when to reach for the full lessons.md.
  2. Monitor. Check that the deployed changes behave as expected in their target environment. Note any anomalies.
  3. Update documentation. Ensure project docs reflect the new state:
    • README or user-facing docs updated if behavior changed
    • Architecture docs updated if new components were added
    • API docs updated if endpoints changed
  4. Gather feedback. Collect user/team feedback on the delivered feature.
  5. Record known issues. Document any edge cases, limitations, or technical debt introduced. If the project has a knowledge graph, record debt as entities (aidlc knowledge add --type debt …) and update facts invalidated by code changes (aidlc knowledge update / verify); list candidates with aidlc knowledge stale --check-git.
  6. Plan follow-up. If feedback or monitoring reveals needed improvements, document them as potential future lifecycle instances.
  7. Close the instance. When maintenance tasks are complete, mark the lifecycle instance as done.

Exit Criteria

  • Every artifact the template's maintenance phase requires exists, with post-deployment status
  • Documentation is updated to reflect the delivered changes
  • No critical issues remain unaddressed
  • Follow-up items are documented (even if deferred to new instances)

Security Confirmation

If maintenance involves:

  • Modifying production configuration
  • Rotating credentials or updating access controls
  • Patching security vulnerabilities

You MUST describe the change, confirm the target environment, and wait for explicit user approval before proceeding.

Guidance

{{guidance:secure-defaults}}

Completion

{{glossary:retrospective}}

For maintenance-terminal instances the completion moment already fired on maintenance entry (see aidlc-deployment) — entering this phase means the instance is complete and its retrospective has run or is pending. Do not fire on-instance-complete again when closing the phase.

When exit criteria are met, update phase-maintenance.yaml status to complete and append a transition record to transitions.log. If no retrospective exists for the instance (legacy completion paths), offer to run the aidlc-retrospective skill.