mirror of
https://bitbucket.org/siakitem/my-pi.git
synced 2026-08-28 08:35:57 +00:00
46 lines
2.6 KiB
Markdown
46 lines
2.6 KiB
Markdown
---
|
||
issue: 110
|
||
issue_title: "refactor: split external-directory.ts into focused modules"
|
||
---
|
||
|
||
# Retro: #110 — split external-directory into focused modules
|
||
|
||
## Final Retrospective (2026-05-07T16:15:00Z)
|
||
|
||
### Session summary
|
||
|
||
Split `src/external-directory.ts` (~760 lines, 4 concerns) into `src/node-modules-discovery.ts`, `src/path-utils.ts` (extended from #109), `src/handlers/gates/external-directory-messages.ts`, and `src/handlers/gates/bash-path-extractor.ts`.
|
||
Initially preserved the original file as a barrel re-export; the user's post-ship question exposed the barrel added no value, leading to a follow-up commit that deleted it and colocated gate-specific modules with their consumers.
|
||
Released as v5.6.3 with zero behavioral change.
|
||
|
||
### Observations
|
||
|
||
#### What went well
|
||
|
||
- **Sequencing with #109 paid off.**
|
||
The user asked whether to do #109 or #110 first; recommending #109 first meant `path-utils.ts` already existed when #110 started, eliminating a `path-classification.ts` that would have been immediately renamed.
|
||
- **TDD extraction was clean.**
|
||
5 steps, all green at every commit.
|
||
The incremental extract-then-re-export-from-barrel pattern meant no downstream test ever broke during the extraction.
|
||
- **Post-ship review caught the real abstraction gap.**
|
||
The user's question "is what we really need a higher level abstraction?"
|
||
took ~10 minutes of import analysis to answer definitively.
|
||
The follow-up commit was small (12 files, +24/−49 lines) because the extraction was already done — only import paths changed.
|
||
|
||
#### What caused friction (agent side)
|
||
|
||
- `premature-convergence` — The plan specified "keep `external-directory.ts` as a barrel re-export" without analyzing whether any consumer actually needed the aggregation.
|
||
Every consumer used symbols from 1–2 underlying modules; no consumer needed all 20+ symbols together.
|
||
The barrel was "these things used to be in one file" masquerading as an API boundary.
|
||
Impact: one extra commit after the issue was closed and shipped, plus re-running CI.
|
||
User-caught.
|
||
- `instruction-violation` — Wrote `#109` at the start of a markdown line in the updated plan, which markdownlint parsed as an ATX H1 heading (same issue as #109 retro).
|
||
Required a commit retry after the pre-commit hook caught it.
|
||
Impact: one failed commit attempt, minor.
|
||
Self-identified via hook output.
|
||
|
||
#### What caused friction (user side)
|
||
|
||
- The user's post-ship question was the most valuable intervention in the session — it transformed a mechanical refactoring into a module-placement decision.
|
||
Earlier involvement (e.g., during planning) could have avoided the barrel entirely, but the cost was low since the follow-up was small.
|