DevFoundry/.devfoundry/improvement-log.md

Improvement Log

Append-only record of retrospectives run by the Process Improver persona, per .devfoundry/skills/process-retrospective.md. Each entry is dated and tied to a spec ID. When the same friction (category + affected file) recurs 3+ times, it must be escalated into a proposed edit to the relevant rule, skill, persona, or reference file.

Do not edit or delete past entries. Correct a wrong entry by appending a new one that references it. The Friction Tally below is the one mutable part of this file and is updated in place as entries are appended.

Friction Tally

Maintained by the Process Improver: on every new log entry below whose Category is not none, update the count and spec-ID list here for that entry's Category + affected file. This is what makes the “3+ occurrences” escalation rule in .devfoundry/skills/process-retrospective.md step 7 checkable at a glance instead of requiring a full re-read of the log. Entries with Category none (clean runs) are never tallied here — they are not recurring problems and must not trigger escalation.

Category	Affected file	Count	Spec IDs
reference-gap	.devfoundry/references/asp-classic-framework.md	1	SPEC-004
interview-gap	.devfoundry/skills/spec-interview.md	1	SPEC-005

---

2026-08-19 — SPEC-001

• 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: none
• Category: none
• Affected file: none
• Proposed change: none
• Status: LOGGED

2026-08-20 — SPEC-002

• What worked: Cloning and reading the real RouteKit framework repo before writing .devfoundry/references/asp-classic-framework.md avoided inventing conventions; asking three short blocking questions (multi-session Access, framework repo location, QA-rule confirmation) up front let the whole change land in one pass.
• Friction: none
• Category: none
• Affected file: none
• Proposed change: none
• Status: LOGGED

2026-08-19 — SPEC-003

• What worked: The new docs/process-checks.md made verification straightforward, and the checks caught one small regex mismatch before closeout.
• Friction: none
• Category: none
• Affected file: none
• Proposed change: none
• Status: LOGGED

2026-08-19 — SPEC-004

• What worked: This was the first non-meta spec — it bootstrapped the RouteKit framework into the repo for real. Cloning the actual source instead of trusting prior documentation surfaced two concrete problems before they became runtime bugs: leftover domain-specific artifacts misdescribed as a “generic starter,” and an IIS Express multi-site startup quirk. Querying the .accdb's real schema via ADODB before running any migration, and hitting each aspunit manifest page directly with ?task=test instead of trying to curl the JS-driven browser runner, produced real, verifiable pass/fail output (26/26 tests) rather than a checklist claim.
• Friction: .devfoundry/references/asp-classic-framework.md (written in SPEC-002, from reading the framework repo) didn't mention that a vendored checkout can carry leftover non-generic artifacts needing a schema cross-check, or that IIS Express needs one process per site despite serverAutoStart="true" on all of them. Both gaps were found and fixed in the same spec, not left for a future recurrence.
• Category: reference-gap
• Affected file: .devfoundry/references/asp-classic-framework.md
• Proposed change: Added a “Verifying a Vendored Checkout” section and an IIS Express multi-site note directly to asp-classic-framework.md (applied immediately — first occurrence, below the 3-occurrence escalation threshold, but the fix was low-risk/additive documentation so it was applied rather than only proposed).
• Status: APPLIED

2026-08-19 — SPEC-005

• What worked: Treating “undo SPEC-004's decision” as its own spec instead of an off-process cleanup kept an honest audit trail: SPEC-004 stays accurate history of what was built and verified, SPEC-005 records why it was reverted. Reusing SPEC-004's own Target Files line as the exact removal checklist made the revert trivial to verify completely and made it easy to keep the reusable parts (asp-classic-framework.md) while removing the instance-specific parts (the vendored app, environments.md's real values).
• Friction: Nothing in the process caught, before SPEC-004 started, that vendoring a live app into DevFoundry's own repo (rather than a separate project repo adopting DevFoundry) was the wrong target. The spec-interview and Solution Architect steps don't currently ask that question.
• Category: interview-gap
• Affected file: .devfoundry/skills/spec-interview.md
• Proposed change: Not yet escalated — first occurrence of this specific gap (below the 3-occurrence threshold). If a future spec repeats this same “which repo should this actually target” confusion, escalate by adding an explicit question to spec-interview.md step 2 (or a new step) asking whether the work belongs in this repo or in a separate project repo that adopts DevFoundry.
• Status: LOGGED

2026-08-19 — SPEC-006

• What worked: Asking two direct clarifying questions before writing anything (one-time adoption reset vs. recurring per-spec action; delete vs. cold-storage disposition) avoided building a more destructive mechanism than intended — “clear the archive” had a plausible reading that would have silently wiped audit trail on every new spec.
• Friction: none
• Category: none
• Affected file: none
• Proposed change: none
• Status: LOGGED