Lessons Learned: Hook Efficiency RFC Analysis

Date: 2026-01-29 Context: Pre-sprint analysis of RFC-Hook-Efficiency-Improvements Tags: architecture, hooks, performance, over-engineering

Summary

During pre-sprint analysis of the Hook Efficiency RFC, critical insights emerged about the balance between optimization and architectural simplicity. This document captures lessons to apply when reviewing projman workflows in future versions.

Key Lessons

1. Isolation is a Feature, Not a Bug

Observation: The RFC proposed consolidating 6 SessionStart hooks into a single dispatcher.

Problem: Current hooks are independent and self-contained. Each can fail without affecting others. A dispatcher creates a single point of failure.

Lesson: Before consolidating independent components, evaluate whether their isolation provides value. Sometimes "duplication" is actually resilience.

Apply to projman: When reviewing agent workflows, resist the urge to merge agents into a single orchestrator. The four-agent model (Planner, Orchestrator, Executor, Reviewer) provides isolation - if one agent's prompt is buggy, others still work.

2. Measure Before Optimizing

Observation: RFC claimed 200-500ms session startup overhead without baseline measurements.

Problem: Proposed architectural changes (dispatcher, shared library) based on estimates, not data.

Lesson: Before any performance optimization:

Establish baseline measurements
Identify the actual bottleneck (is it process spawning? network calls? file I/O?)
Validate that proposed solution addresses the actual bottleneck

Apply to projman: Before refactoring sprint workflows, profile actual execution. Which agent calls are slow? Is it the MCP tools, the prompts, or the response processing?

3. Shared Libraries Create Coupling

Observation: RFC proposed a shared hook library (scripts/hooks/lib/common.sh).

Problem: Currently each hook is one self-contained file (~30-100 lines). With a shared library:

Debugging requires understanding multiple files
Changes to library affect all hooks
Path resolution becomes complex (hooks run from different contexts)

Lesson: Shared code reduces duplication but increases coupling. For small, independent scripts, some duplication is acceptable.

Apply to projman: Resist creating "shared agent utilities" or "common prompt templates" unless the duplication is actually causing bugs. Each agent's prompt should be readable in isolation.

4. Easy Wins vs Architectural Changes

Observation: RFC mixed trivial fixes with major architectural changes.

Trivial fixes (do these):

Remove viz-platform echo hook (zero value)
Flip clarity-assist to opt-in (config change)
Add project-hygiene cooldown (simple logic)

Architectural changes (question these):

Session dispatcher (new abstraction layer)
Shared hook library (new dependency)

Lesson: Separate quick wins from architectural changes. Do quick wins immediately. Question whether architectural changes are necessary.

Apply to projman: When reviewing projman, identify quick fixes vs workflow redesigns. Don't let a "while we're at it" mentality turn a bug fix into a rewrite.

5. The Current System Works

Observation: User confirmed "the marketplace is working."

Problem: RFC proposed changes to fix problems that weren't causing pain.

Lesson: Working software has value. Refactoring for "cleanliness" or "performance" without user-perceived problems is risky.

Apply to projman: Before changing projman workflows, ask:

What specific problem does this solve?
Is the user experiencing this problem?
What's the minimum change that fixes it?

6. Hooks Already Have Early-Exit Patterns

Observation: RFC claimed git-flow hooks trigger on "every bash command" inefficiently.

Reality: The hooks already check command type early and exit if not relevant (lines 14-16, 42-44 in branch-check.sh).

Lesson: Read the code before proposing optimizations. The "problem" may already be solved.

Apply to projman: Before adding optimizations to agent workflows, verify the current implementation doesn't already handle the case.

Anti-Patterns to Avoid

Anti-Pattern	Description	Alternative
Premature Consolidation	Merging independent components before proving benefit	Keep components isolated unless coupling provides clear value
Estimate-Driven Optimization	Making changes based on guesses about performance	Measure first, optimize second
Shared Library Creep	Extracting common code "for reuse"	Accept some duplication for isolation
Architecture Astronautics	Designing for hypothetical future needs	Solve today's problems with today's code
Fixing Working Code	Refactoring because it "could be better"	Only change what causes actual problems

Questions to Ask Before Major Changes

Is this solving a real problem? (not hypothetical)
Has the problem been measured? (not estimated)
What's the minimum change that fixes it?
What breaks if this change has a bug? (blast radius)
Can this be easily reverted?
Will future maintainers understand why this exists?

Recommendations for projman Workflow Review

When we do the full projman workflow review, apply these lessons:

Start with user pain points - What's actually frustrating? Not what could theoretically be better.
Profile before changing - Which agent calls are slow? Which commands are confusing? Get data.
Preserve agent isolation - The four-agent model works. Don't merge agents without strong justification.
Document the "why" - For every change, write why it exists. Future you will thank present you.
Small PRs - Change one thing at a time. Easier to review, easier to revert.
Test with real workflows - Not just unit tests, but actual sprint planning sessions.

Conclusion

The Hook Efficiency RFC had valid goals (reduce overhead) but proposed solutions that traded simplicity for complexity. The analysis revealed that quick wins (removing unused hooks, config changes) provide most of the benefit without architectural risk.

This pattern - identifying quick wins vs over-engineered solutions - should guide future projman improvements.

This lesson learned was created during sprint planning for hook efficiency improvements. To be referenced during projman workflow review (future version).