FACTORY-HYGIENE #39: hot-file-path detector#37
Merged
Conversation
New hygiene class surfaced by PR #31's 5-file merge-tangle. Detector is the one-liner: git log --since="60 days ago" --name-only --pretty=format: \ | grep -v '^$' | sort | uniq -c | sort -rn | head -25 No index needed — git history *is* the index. Heuristic: >20 changes / 60d on a single monolithic doc = investigate; >30 = refactor candidate (tune after 5-10 rounds of observation). Per-file decision is one of four: - refactor-split (per-row, per-round, per-section) - consolidate-reduce (merge with a sibling) - accept-as-append-only (legitimately append-only → split into per-round files rather than trimming) - observe Empirical ranking at landing (60-day window, 2026-04-21): 33 docs/ROUND-HISTORY.md ← #1; merge-tangle source 26 docs/BACKLOG.md ← ADR already in-flight 14 docs/VISION.md 13 docs/CURRENT-ROUND.md 11 docs/WINS.md 10 docs/DEBT.md Pair with merge-tangle fingerprints (PR #31 §9 incident log) — a hot file is worse if also in a recent conflict list. Triggered by Aaron 2026-04-21 ("hot file path detector probably needs refactor if we find hot git file paths as we just noticed, another hygene" + "detecting hot files i wonder if you can just use git history for that and see what changes the most"). Full reasoning + scope in memory/feedback_hot_file_path_detector_hygiene.md (agent-memory file, not in repo). Scope: factory. Ships to adopters via the command-line recipe (any repo runs the same `git log` against its own tree). Pairs with existing rows #22 (symmetry-opportunities) and #23 (missing-hygiene-class gap-finder) — both meta-audits that sweep for structural pressure. This row targets churn-pressure specifically. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new factory-hygiene table entry (#39) to codify a lightweight “hot file path” churn detector (based on git log history) intended to flag refactor candidates before merge conflicts accumulate.
Changes:
- Add row #39 “Hot-file-path detector” to
docs/FACTORY-HYGIENE.md. - Document the detector command, thresholds, and the per-file decision taxonomy (
refactor-split,consolidate-reduce,accept-as-append-only,observe). - Add cross-references to related hygiene items / research / decisions.
| | 36 | Incorrectly-scoped gap-finder (retrospective) | Every 5-10 rounds (proposed — Aaron 2026-04-20 late) | TBD — candidate skill (queued in BACKLOG P1 alongside row 35); may collapse into a single "scope-hygiene" skill pending row-consolidation research | factory | Retrospective sweep for items whose scope tag is **present but wrong** — factory-level rules tagged `project: zeta`, Zeta-specific rules tagged factory, over-broad / under-broad declarations. Distinct from row 35 (missing tag) — this is *tag-exists-but-incorrect*. Trigger examples: Aaron's 2026-04-20 catch of "cheap-but-zeta-specific governance" in the skill-edit-gating-tiers research doc (factory-scope governance mislabeled as Zeta-specific). Flags candidates to HUMAN-BACKLOG as `scope-correction` rows. | Audit doc per round + HB row per mis-scoped item | `feedback_factory_default_scope_unless_db_specific.md` + `project_factory_reuse_beyond_zeta_constraint.md` + `user_absorb_time_filter_always_wanted.md` | | ||
| | 37 | WIP-limit discipline (Kanban) | Round open + per-persona session-open (always-on, not triggered) | All agents (self-administered) + Architect for cross-persona visibility | factory | Per-persona in-flight work cap (suggested 3: proposals / findings / drafts not yet landed); cross-persona cap (suggested 7 under architect-bottleneck review queue per GOVERNANCE §11). Over-cap flags to HUMAN-BACKLOG as `wip-pressure` rows. Always-on discipline per `docs/FACTORY-METHODOLOGIES.md` pull-vs-always-on criterion (this row is always-on, therefore not a skill). Cap numbers are *suggestions*; tune after 5-10 rounds of observation per Six Sigma Measure → Improve loop. | Inline self-report + HUMAN-BACKLOG row if over-cap + Architect notebook tally column | `user_kanban_six_sigma_process_preference.md` + `docs/FACTORY-METHODOLOGIES.md` + `docs/research/kanban-six-sigma-factory-process.md` + GOVERNANCE.md §11 | | ||
| | 38 | Harness-surface cadenced audit | Every 5-10 rounds per populated harness (same cadence as skill-tune-up and agent-QOL). Stubs don't tick. | Per populated harness: Claude owned by Architect (Kenji) **interim** until a dedicated harness-guide role is decided; plugin-provided `claude-code-guide` agent (Anthropic official plugin cache, not a local `.claude/agents/` file) is a reference resource consulted during audit, not the audit runner. Codex / Cursor / GitHub Copilot / Antigravity / Amazon Q / Kiro — TBD when populated (either dedicated guide per harness or a shared multi-harness guide). | factory | Audit each populated harness's platform surfaces for new features, cut features, behavioural changes. For Claude: model / Code CLI / Desktop app / Agent SDK / API. For Codex / Cursor / Copilot / Antigravity / Amazon Q / Kiro: per-harness equivalents inventoried at first-populated audit. Primary feature-comparison axis per harness is skill-authoring + eval-driven feedback loop (the Claude-Code feature that made it Aaron's primary choice — `memory/user_skill_creator_killer_feature_feedback_loop.md`). Update `docs/HARNESS-SURFACES.md` living inventory with adoption statuses (adopted / watched / untested / rejected / stub). When audit surfaces drift, either adopt (ADR if Tier-3), retire the workaround the new feature obsoletes, or record explicit rejection in `docs/WONT-DO.md`. Integration-point tests per harness are owned by a *different* harness per the capability-boundary rule (a harness cannot honestly self-verify its own factory integration from within itself). Triggering incidents: 2026-04-20 AutoMemory miss (Anthropic's Q1-2026 feature mis-attributed as factory-native) + 2026-04-20 multi-harness expansion (Aaron: factory supports multiple harnesses; each tests the others'). | `docs/HARNESS-SURFACES.md` audit log row per cycle per populated harness; ADRs under `docs/DECISIONS/` for Tier-3 adoptions; `docs/research/meta-wins-log.md` entry when a pre-existing factory assumption is found to have been wrong | `feedback_claude_surface_cadence_research.md` + `feedback_multi_harness_support_each_tests_own_integration.md` + `user_skill_creator_killer_feature_feedback_loop.md` + `reference_automemory_anthropic_feature.md` + `reference_autodream_feature.md` | | ||
| | 39 | Hot-file-path detector | Round-cadence (every round close) or every 5-10 rounds — whichever catches churn drift before the next merge-tangle. Proposed 2026-04-21. | TBD — candidate capability skill `hot-file-detector` (queued in BACKLOG P1); Architect runs inline until the skill lands. | factory (ships to adopters as a command-line recipe) | `git log --since="60 days ago" --name-only --pretty=format: \| grep -v '^$' \| sort \| uniq -c \| sort -rn \| head -25` — git history *is* the index. Heuristic threshold: >20 changes in 60d on a single monolithic doc = investigate; >30 = refactor candidate (tune after 5-10 rounds). Per-file decision is one of four: `refactor-split` (per-row, per-round, per-section), `consolidate-reduce` (merge with a sibling), `accept-as-append-only` (legitimately append-only → split into per-round files rather than trimming), or `observe`. Pair with merge-tangle fingerprints from `docs/research/parallel-worktree-safety-2026-04-22.md` §9 — a hot file is worse if also in a recent conflict list. Triggering incident: PR #31 5-file merge-tangle (2026-04-21) where `docs/ROUND-HISTORY.md` at 33 changes / 60d was the #1 conflict source, and `docs/BACKLOG.md` at 26 already has an in-flight split ADR. | Audit doc per cycle listing top-N hot paths + per-file decision; BACKLOG rows for refactor-split candidates; ADRs for structural changes. | `feedback_hot_file_path_detector_hygiene.md` + `docs/DECISIONS/2026-04-22-backlog-per-row-file-restructure.md` (same pattern) | |
| | 36 | Incorrectly-scoped gap-finder (retrospective) | Every 5-10 rounds (proposed — Aaron 2026-04-20 late) | TBD — candidate skill (queued in BACKLOG P1 alongside row 35); may collapse into a single "scope-hygiene" skill pending row-consolidation research | factory | Retrospective sweep for items whose scope tag is **present but wrong** — factory-level rules tagged `project: zeta`, Zeta-specific rules tagged factory, over-broad / under-broad declarations. Distinct from row 35 (missing tag) — this is *tag-exists-but-incorrect*. Trigger examples: Aaron's 2026-04-20 catch of "cheap-but-zeta-specific governance" in the skill-edit-gating-tiers research doc (factory-scope governance mislabeled as Zeta-specific). Flags candidates to HUMAN-BACKLOG as `scope-correction` rows. | Audit doc per round + HB row per mis-scoped item | `feedback_factory_default_scope_unless_db_specific.md` + `project_factory_reuse_beyond_zeta_constraint.md` + `user_absorb_time_filter_always_wanted.md` | | ||
| | 37 | WIP-limit discipline (Kanban) | Round open + per-persona session-open (always-on, not triggered) | All agents (self-administered) + Architect for cross-persona visibility | factory | Per-persona in-flight work cap (suggested 3: proposals / findings / drafts not yet landed); cross-persona cap (suggested 7 under architect-bottleneck review queue per GOVERNANCE §11). Over-cap flags to HUMAN-BACKLOG as `wip-pressure` rows. Always-on discipline per `docs/FACTORY-METHODOLOGIES.md` pull-vs-always-on criterion (this row is always-on, therefore not a skill). Cap numbers are *suggestions*; tune after 5-10 rounds of observation per Six Sigma Measure → Improve loop. | Inline self-report + HUMAN-BACKLOG row if over-cap + Architect notebook tally column | `user_kanban_six_sigma_process_preference.md` + `docs/FACTORY-METHODOLOGIES.md` + `docs/research/kanban-six-sigma-factory-process.md` + GOVERNANCE.md §11 | | ||
| | 38 | Harness-surface cadenced audit | Every 5-10 rounds per populated harness (same cadence as skill-tune-up and agent-QOL). Stubs don't tick. | Per populated harness: Claude owned by Architect (Kenji) **interim** until a dedicated harness-guide role is decided; plugin-provided `claude-code-guide` agent (Anthropic official plugin cache, not a local `.claude/agents/` file) is a reference resource consulted during audit, not the audit runner. Codex / Cursor / GitHub Copilot / Antigravity / Amazon Q / Kiro — TBD when populated (either dedicated guide per harness or a shared multi-harness guide). | factory | Audit each populated harness's platform surfaces for new features, cut features, behavioural changes. For Claude: model / Code CLI / Desktop app / Agent SDK / API. For Codex / Cursor / Copilot / Antigravity / Amazon Q / Kiro: per-harness equivalents inventoried at first-populated audit. Primary feature-comparison axis per harness is skill-authoring + eval-driven feedback loop (the Claude-Code feature that made it Aaron's primary choice — `memory/user_skill_creator_killer_feature_feedback_loop.md`). Update `docs/HARNESS-SURFACES.md` living inventory with adoption statuses (adopted / watched / untested / rejected / stub). When audit surfaces drift, either adopt (ADR if Tier-3), retire the workaround the new feature obsoletes, or record explicit rejection in `docs/WONT-DO.md`. Integration-point tests per harness are owned by a *different* harness per the capability-boundary rule (a harness cannot honestly self-verify its own factory integration from within itself). Triggering incidents: 2026-04-20 AutoMemory miss (Anthropic's Q1-2026 feature mis-attributed as factory-native) + 2026-04-20 multi-harness expansion (Aaron: factory supports multiple harnesses; each tests the others'). | `docs/HARNESS-SURFACES.md` audit log row per cycle per populated harness; ADRs under `docs/DECISIONS/` for Tier-3 adoptions; `docs/research/meta-wins-log.md` entry when a pre-existing factory assumption is found to have been wrong | `feedback_claude_surface_cadence_research.md` + `feedback_multi_harness_support_each_tests_own_integration.md` + `user_skill_creator_killer_feature_feedback_loop.md` + `reference_automemory_anthropic_feature.md` + `reference_autodream_feature.md` | | ||
| | 39 | Hot-file-path detector | Round-cadence (every round close) or every 5-10 rounds — whichever catches churn drift before the next merge-tangle. Proposed 2026-04-21. | TBD — candidate capability skill `hot-file-detector` (queued in BACKLOG P1); Architect runs inline until the skill lands. | factory (ships to adopters as a command-line recipe) | `git log --since="60 days ago" --name-only --pretty=format: \| grep -v '^$' \| sort \| uniq -c \| sort -rn \| head -25` — git history *is* the index. Heuristic threshold: >20 changes in 60d on a single monolithic doc = investigate; >30 = refactor candidate (tune after 5-10 rounds). Per-file decision is one of four: `refactor-split` (per-row, per-round, per-section), `consolidate-reduce` (merge with a sibling), `accept-as-append-only` (legitimately append-only → split into per-round files rather than trimming), or `observe`. Pair with merge-tangle fingerprints from `docs/research/parallel-worktree-safety-2026-04-22.md` §9 — a hot file is worse if also in a recent conflict list. Triggering incident: PR #31 5-file merge-tangle (2026-04-21) where `docs/ROUND-HISTORY.md` at 33 changes / 60d was the #1 conflict source, and `docs/BACKLOG.md` at 26 already has an in-flight split ADR. | Audit doc per cycle listing top-N hot paths + per-file decision; BACKLOG rows for refactor-split candidates; ADRs for structural changes. | `feedback_hot_file_path_detector_hygiene.md` + `docs/DECISIONS/2026-04-22-backlog-per-row-file-restructure.md` (same pattern) | |
| | 36 | Incorrectly-scoped gap-finder (retrospective) | Every 5-10 rounds (proposed — Aaron 2026-04-20 late) | TBD — candidate skill (queued in BACKLOG P1 alongside row 35); may collapse into a single "scope-hygiene" skill pending row-consolidation research | factory | Retrospective sweep for items whose scope tag is **present but wrong** — factory-level rules tagged `project: zeta`, Zeta-specific rules tagged factory, over-broad / under-broad declarations. Distinct from row 35 (missing tag) — this is *tag-exists-but-incorrect*. Trigger examples: Aaron's 2026-04-20 catch of "cheap-but-zeta-specific governance" in the skill-edit-gating-tiers research doc (factory-scope governance mislabeled as Zeta-specific). Flags candidates to HUMAN-BACKLOG as `scope-correction` rows. | Audit doc per round + HB row per mis-scoped item | `feedback_factory_default_scope_unless_db_specific.md` + `project_factory_reuse_beyond_zeta_constraint.md` + `user_absorb_time_filter_always_wanted.md` | | ||
| | 37 | WIP-limit discipline (Kanban) | Round open + per-persona session-open (always-on, not triggered) | All agents (self-administered) + Architect for cross-persona visibility | factory | Per-persona in-flight work cap (suggested 3: proposals / findings / drafts not yet landed); cross-persona cap (suggested 7 under architect-bottleneck review queue per GOVERNANCE §11). Over-cap flags to HUMAN-BACKLOG as `wip-pressure` rows. Always-on discipline per `docs/FACTORY-METHODOLOGIES.md` pull-vs-always-on criterion (this row is always-on, therefore not a skill). Cap numbers are *suggestions*; tune after 5-10 rounds of observation per Six Sigma Measure → Improve loop. | Inline self-report + HUMAN-BACKLOG row if over-cap + Architect notebook tally column | `user_kanban_six_sigma_process_preference.md` + `docs/FACTORY-METHODOLOGIES.md` + `docs/research/kanban-six-sigma-factory-process.md` + GOVERNANCE.md §11 | | ||
| | 38 | Harness-surface cadenced audit | Every 5-10 rounds per populated harness (same cadence as skill-tune-up and agent-QOL). Stubs don't tick. | Per populated harness: Claude owned by Architect (Kenji) **interim** until a dedicated harness-guide role is decided; plugin-provided `claude-code-guide` agent (Anthropic official plugin cache, not a local `.claude/agents/` file) is a reference resource consulted during audit, not the audit runner. Codex / Cursor / GitHub Copilot / Antigravity / Amazon Q / Kiro — TBD when populated (either dedicated guide per harness or a shared multi-harness guide). | factory | Audit each populated harness's platform surfaces for new features, cut features, behavioural changes. For Claude: model / Code CLI / Desktop app / Agent SDK / API. For Codex / Cursor / Copilot / Antigravity / Amazon Q / Kiro: per-harness equivalents inventoried at first-populated audit. Primary feature-comparison axis per harness is skill-authoring + eval-driven feedback loop (the Claude-Code feature that made it Aaron's primary choice — `memory/user_skill_creator_killer_feature_feedback_loop.md`). Update `docs/HARNESS-SURFACES.md` living inventory with adoption statuses (adopted / watched / untested / rejected / stub). When audit surfaces drift, either adopt (ADR if Tier-3), retire the workaround the new feature obsoletes, or record explicit rejection in `docs/WONT-DO.md`. Integration-point tests per harness are owned by a *different* harness per the capability-boundary rule (a harness cannot honestly self-verify its own factory integration from within itself). Triggering incidents: 2026-04-20 AutoMemory miss (Anthropic's Q1-2026 feature mis-attributed as factory-native) + 2026-04-20 multi-harness expansion (Aaron: factory supports multiple harnesses; each tests the others'). | `docs/HARNESS-SURFACES.md` audit log row per cycle per populated harness; ADRs under `docs/DECISIONS/` for Tier-3 adoptions; `docs/research/meta-wins-log.md` entry when a pre-existing factory assumption is found to have been wrong | `feedback_claude_surface_cadence_research.md` + `feedback_multi_harness_support_each_tests_own_integration.md` + `user_skill_creator_killer_feature_feedback_loop.md` + `reference_automemory_anthropic_feature.md` + `reference_autodream_feature.md` | | ||
| | 39 | Hot-file-path detector | Round-cadence (every round close) or every 5-10 rounds — whichever catches churn drift before the next merge-tangle. Proposed 2026-04-21. | TBD — candidate capability skill `hot-file-detector` (queued in BACKLOG P1); Architect runs inline until the skill lands. | factory (ships to adopters as a command-line recipe) | `git log --since="60 days ago" --name-only --pretty=format: \| grep -v '^$' \| sort \| uniq -c \| sort -rn \| head -25` — git history *is* the index. Heuristic threshold: >20 changes in 60d on a single monolithic doc = investigate; >30 = refactor candidate (tune after 5-10 rounds). Per-file decision is one of four: `refactor-split` (per-row, per-round, per-section), `consolidate-reduce` (merge with a sibling), `accept-as-append-only` (legitimately append-only → split into per-round files rather than trimming), or `observe`. Pair with merge-tangle fingerprints from `docs/research/parallel-worktree-safety-2026-04-22.md` §9 — a hot file is worse if also in a recent conflict list. Triggering incident: PR #31 5-file merge-tangle (2026-04-21) where `docs/ROUND-HISTORY.md` at 33 changes / 60d was the #1 conflict source, and `docs/BACKLOG.md` at 26 already has an in-flight split ADR. | Audit doc per cycle listing top-N hot paths + per-file decision; BACKLOG rows for refactor-split candidates; ADRs for structural changes. | `feedback_hot_file_path_detector_hygiene.md` + `docs/DECISIONS/2026-04-22-backlog-per-row-file-restructure.md` (same pattern) | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/FACTORY-HYGIENE.mdrow WONT-DO: add ADR-vocabulary Status line per entry #39: hot-file-path detector.Why now
PR #31 hit a 5-file merge-tangle that surfaced
docs/ROUND-HISTORY.mdas the #1 conflict source. A 60-day churn ranking shows the same file at 33 changes (next:BACKLOG.mdat 26, which already has an in-flight split ADR). The hygiene class codifies what the BACKLOG ADR already did implicitly: hot paths are structural-pressure candidates.The detector
Threshold heuristic (tunable after 5-10 rounds): >20/60d investigate, >30/60d refactor candidate.
Per-file decision set
One of four —
refactor-split,consolidate-reduce,accept-as-append-only,observe.Pairing
docs/research/parallel-worktree-safety-2026-04-22.md§9 — cross-reference for worse-if-also-conflict-prone.Test plan
markdownlint-cli2 docs/FACTORY-HYGIENE.mdlocal green (no new lint violations).🤖 Generated with Claude Code