DevFoundry/specs/archive/SPEC-001-process-doc-cleanup.md

SPEC-001: Process Documentation Cleanup

• Status: COMPLETED
• Stack: DevFoundry process documentation
• Target Files: AGENTS.md, README.md, specs/.spec-counter, specs/templates/spec-template.md, .devfoundry/skills/spec-interview.md, .devfoundry/skills/technical-spec.md, .devfoundry/skills/regression-check.md, .devfoundry/skills/process-retrospective.md, .devfoundry/personas/solution-architect.md, .devfoundry/improvement-log.md

---

1. Business Context & Goal

The DevFoundry scaffold is intended to be followed by coding agents without ambiguity. A repo review found several small inconsistencies that could cause process drift: mixed spec filename conventions, unclear task-versus-spec completion language, timestamp requirements that are referenced by QA but missing from the main spec template, implicit status transition ownership, and an append-only log with a mutable tally table.

No other active specs exist, so there are no target-file conflicts.

2. Acceptance Criteria (Given / When / Then)

• AC-1: Given an agent needs to create a spec, when it reads AGENTS, README, technical-spec, and Solution Architect docs, then all docs use the SPEC-<id>-<short-name>.md filename convention.
• AC-2: Given an implementation task is completed, when the Builder marks it done, then the docs distinguish task-level completion from spec-level QA approval.
• AC-3: Given QA checks TDD ordering, when it reviews the spec, then the main spec template includes completed: <YYYY-MM-DD HH:MM> timestamp guidance for test/manual-verification and implementation tasks.
• AC-4: Given a draft spec is prepared, when the user reviews it, then the docs provide a readiness checklist before approval.
• AC-5: Given a spec moves through the lifecycle, when an agent reads the README, then actor-owned status transitions are explicit.
• AC-6: Given the Process Improver updates the improvement log, when it reads the log instructions, then entries are append-only while the Friction Tally is explicitly mutable.
• AC-7: Given project-specific runtime/reference details are missing, when requirements are gathered, then the process prompts for them early enough to prevent Builder/QA guesswork.

3. Technical Design & Contracts

• Data Model / Schema Changes: None.
• Functions / APIs / Interfaces: None.
• Architecture: Documentation-only process update; no application architecture affected.
• Error Handling Strategy: Preserve existing safety gates and avoid weakening any rule. Documentation changes must be consistent across all listed files.

4. Implementation Plan (Atomic Steps, TDD-ordered)

• Step 1 (verification authoring): Write the manual verification checklist in this spec before changing process docs — files: specs/active/SPEC-001-process-doc-cleanup.md, specs/.spec-counter — completed: 2026-08-19 22:14
• Step 2 (implementation): Normalize spec filename references and task/spec completion language — files: AGENTS.md, README.md, .devfoundry/personas/solution-architect.md, .devfoundry/skills/process-retrospective.md — completed: 2026-08-19 22:14
• Step 3 (implementation): Add spec readiness, timestamp, status-transition, reference-readiness, and improvement-log mutability guidance — files: README.md, specs/templates/spec-template.md, .devfoundry/skills/spec-interview.md, .devfoundry/skills/technical-spec.md, .devfoundry/skills/regression-check.md, .devfoundry/improvement-log.md — completed: 2026-08-19 22:14
• Step 4 (verification): Search the updated docs for stale filename patterns and confirm each acceptance criterion is reflected — files: listed target files — completed: 2026-08-19 22:17

5. Verification & Regression Plan

• Verify AC-1 by searching for stale specs/active/<id>-<name>.md, specs/active/<id>-<short-name>.md, and specs/archive/<id>-<name>.md references.
• Verify AC-2 by confirming Builder task completion and QA spec completion are described separately.
• Verify AC-3 by confirming completed: <YYYY-MM-DD HH:MM> appears in the main spec template.
• Verify AC-4 by confirming a Spec Readiness Checklist exists before approval.
• Verify AC-5 by confirming README contains an actor-owned status transition table.
• Verify AC-6 by confirming the improvement log distinguishes append-only entries from mutable tally updates.
• Verify AC-7 by confirming early project-reference prompts are documented.

6. Retrospective

Filled by the Process Improver per .devfoundry/skills/process-retrospective.md, after QA approval and before archiving.

• What worked: A compact process spec kept the documentation updates scoped, and verification searches caught that the executable interview skill also needed the early-reference prompt.
• Friction (rule/reference/interview gap, or none): none
• Logged in .devfoundry/improvement-log.md: yes