🧹 Maintenance Workflow

[Alan-Jowett]

🧹 Maintenance Workflow

A PromptKit workflow for periodic auditing, drift detection, and semantic cleanup across requirements, design, validation, code, and tests.

This issue proposes a new PromptKit workflow:
a Maintenance Workflow that periodically re‑audits a repository’s semantic artifacts and implementation to detect drift, correct inconsistencies, and keep the system aligned over time.

This becomes the “health check” workflow that complements:

• Spec Extraction Workflow (bootstrap)
• Engineering Workflow (ongoing evolution)

Together, these three workflows form a complete semantic engineering lifecycle.

---

🎯 Goal

Create a PromptKit workflow that can be run at any time to:

1. Re‑scan the repository (requirements, design, validation, code, tests, docs)
2. Detect drift, inconsistencies, and obsolete behaviors
3. Collaborate with the user to clarify intentional vs. accidental drift
4. Generate patches to restore alignment
5. Audit the updated specs and code
6. Produce a PR with the maintenance corrections

This workflow ensures long‑term correctness, clarity, and structural integrity.

---

🧩 Workflow Phases

1. Repository Rescan

The workflow reads:

• requirements.md
• design.md
• validation.md
• source code
• tests
• documentation

It builds a current semantic model of the system.

---

2. Drift Detection

PromptKit identifies:

• missing requirements
• obsolete requirements
• undocumented behaviors
• design inconsistencies
• validation gaps
• code that violates invariants
• tests that no longer match behavior
• dead code or unused interfaces
• architectural erosion

All findings should be categorized by severity and confidence.

---

3. Human Clarification Loop

PromptKit asks the user to confirm or correct each finding:

• “Is this requirement still valid?”
• “Should this obsolete behavior be removed?”
• “Is this drift intentional?”
• “Should this design decision be updated?”
• “Is this test failure expected or a bug?”

This loop continues until all drift is classified.

---

4. Patch Generation

Based on the clarified intent, PromptKit generates:

• requirements patch
• design patch
• validation patch
• code patch
• test patch

Each patch must include traceability back to the drift findings.

---

5. Audit Phase

The workflow audits:

• requirements ↔ design
• design ↔ validation
• validation ↔ code
• code ↔ tests

It emits:

• alignment reports
• invariant checks
• unresolved ambiguities
• recommended follow‑up actions

---

6. Human Approval

The user reviews the proposed maintenance deltas and audit results.

PromptKit iterates until the user approves the updated semantic baseline.

---

7. PR Generation

The workflow produces a PR containing:

• updated requirements.md
• updated design.md
• updated validation.md
• updated code/tests
• drift report
• audit report
• summary of changes
• rationale for each correction

This PR restores the repo to a clean, aligned state.

---

📦 Deliverables

• maintenance-workflow.md workflow definition
• Orchestrator persona
• Drift detection component
• Human‑in‑the‑loop clarification protocol
• Patch generation components
• Audit component
• PR generation component
• Example run on a sample repo

---

🧭 Notes

This workflow completes the PromptKit engineering lifecycle:

1. Spec Extraction Workflow — bootstrap a repo into a semantic baseline
2. Engineering Workflow — evolve the repo in a structured, auditable way
3. Maintenance Workflow — periodically restore alignment and prevent semantic decay

This triad gives PromptKit users a full, multi‑domain engineering system that scales across software, firmware, electrical engineering, mechanical design, and more.

[Alan-Jowett]

Analysis: Existing Coverage and Net-New Work

Almost complete reuse

This workflow has the highest reuse ratio of the triad. Every phase maps to existing (or in-flight) components:

Phase	Existing Component(s)
1. Repository Rescan	No component needed -- just read the files
2. Drift Detection	audit-traceability (D1-D7) + audit-code-compliance (D8-D10) + audit-test-compliance (D11-D13) + specification-drift taxonomy
3. Human Clarification	Same interactive pattern as engineering-workflow
4. Patch Generation	generate-spec-changes + generate-implementation-changes (from #116)
5. Audit	audit-spec-alignment + audit-implementation-alignment (from #116)
6-7. Approval + PR	Same as engineering-workflow Phases 7-8

What's actually new

One orchestration template (maintenance-workflow.md). That's it.

The differentiator is Phase 2 -- running existing audit templates proactively (not in response to a change) and then feeding classified drift findings into the existing patch generation and audit templates from #116.

Key observation

Phases 4-7 of this workflow ARE the engineering-workflow. Once drift is classified, you're generating patches and auditing them -- same spec cycle + implementation cycle. The maintenance workflow could even delegate to the engineering-workflow for each classified drift finding.

Deliverables list refinement

Same pattern as #117:

• Orchestrator persona: Not needed -- configurable personas (specification-analyst for drift detection, domain persona for patches)
• Drift detection component: Already exists -- audit-traceability + audit-code-compliance + audit-test-compliance
• Patch generation / audit / PR components: Already exist or in-flight (Add engineering-workflow: domain-agnostic incremental development pipeline #116)
• Human-in-the-loop clarification protocol: May warrant a small drift-classification protocol that distinguishes intentional vs. accidental drift, but could also be inline instructions

The triad architecture

Spec Extraction (#117) -- bootstrap: no specs --> semantic baseline Engineering Workflow (#116) -- evolve: change --> propagate --> audit --> deliver Maintenance Workflow (#118) -- maintain: detect drift --> classify --> fix --> audit --> deliver \____________________________/ reuses engineering-workflow

All three share the same underlying templates, protocols, formats, and taxonomy. This is the right architecture -- maximum reuse, consistent quality, one taxonomy (D1-D16) across all workflows.