evolve

Self-Evolution Skill

The evolve skill observes how the user works with Claude Code and updates workflow_preferences.md so the orchestrator can adapt to their style. It learns seven dimensions: pacing, depth, workflow ordering, tool preferences, edit size, error recovery, and interaction patterns.

---

When to Run

1. Orchestrator startup — Before entering Phase 1 of a new milestone, run the "Apply" procedure to load current preferences.
2. Session start (automatic) — The session-start.sh hook runs analyze-sessions.py which fully updates workflow_preferences.md — both quantitative stats AND qualitative classifications (pacing, depth, workflow). No LLM involvement needed.
3. On demand — When the user asks to review or reset their workflow preferences.

Note: The system is fully deterministic. The Python script classifies each session's pacing (fast/deliberate/mixed), depth (shallow/deep/mixed), and workflow (pure execution/diagnostic/brainstorm+execute/quick interaction) using tool-usage heuristics. It also applies the confidence counter logic automatically. No pending_session_analysis.json or LLM layer is needed.

---

File Locations

File	Location	Purpose
Raw tool log	~/.claude/project-finisher-data/behavior_log.jsonl	Rolling log from PostToolUse hook (last 100 entries kept)
Preferences	~/.claude/project-finisher-data/workflow_preferences.md	Extracted stable preferences (the "learned" file)

---

Observe & Extract Procedure

At the end of a session, perform the following analysis:

Step 0: Prune the Behavior Log

Before analyzing, trim behavior_log.jsonl to the most recent 100 entries to prevent unbounded growth. Older entries have already been distilled into workflow_preferences.md, so they are safe to discard.

LOG=~/.claude/project-finisher-data/behavior_log.jsonl
if [ -f "$LOG" ] && [ "$(wc -l < "$LOG")" -gt 100 ]; then
  tail -n 100 "$LOG" > "$LOG.tmp" && mv "$LOG.tmp" "$LOG"
fi

Step 1: Reflect on This Session

Analyze the current conversation for these signals:

Pacing signals:

• User message length: short (<20 words) = fast, long (>50 words) = deliberate
• Frequency of "just do it" / "go ahead" / "proceed" = fast
• Frequency of "explain" / "why" / "what are the tradeoffs" = deliberate
• Did the user interrupt a multi-step workflow? = fast
• Did the user ask follow-up questions before acting? = deliberate

Depth signals:

• Did the user request explanations or just code? code-only = shallow, explanations = deep
• Did the user engage with tradeoff analysis? yes = deep
• Did the user read long outputs or ask for summaries? summaries = shallow
• Number of brainstorming rounds before moving to action: 1-2 = shallow, 3+ = deep

Workflow ordering signals:

• Which phases did the user engage with vs. skip?
• Did the user jump to execution before planning?
• Did the user request review/testing or skip it?
• Record the actual phase sequence used

Tool preference signals:

• Read the tool log at ~/.claude/project-finisher-data/behavior_log.jsonl
• Count tool usage frequency for this session
• Note: Agent vs direct tool ratio (Grep/Glob vs Agent)
• Note: Edit vs Write ratio
• Note: Whether user preferred Bash for tasks tools could handle

Edit size signals (from enriched log edit_size field):

• Predominantly small edits (<50 chars net change) = incremental
• Predominantly large edits (>500 chars) = large-rewrite
• Mixed sizes = mixed

Error recovery signals (from enriched log bash_ok field):

• After a Bash failure, next tool is Bash again = retry pattern
• After a Bash failure, next tool is Read/Grep/Glob = investigate pattern
• After a Bash failure, next tool is Edit/Write = fix pattern

Interaction pattern signals (from tool sequence):

• High Read:Edit ratio (≥2:1) = cautious (look-before-edit)
• Low Read:Edit ratio (≤0.5:1) = direct (edit with minimal pre-reading)
• Between = mixed

Step 2: Update Preferences

Read the current workflow_preferences.md (create if it doesn't exist).

For each dimension, apply this update logic:

1. New observation agrees with current preference → Increment the confidence counter. No change needed.
2. New observation disagrees with current preference → Decrement the confidence counter. If confidence drops to 0, flip the preference.
3. No current preference exists → Set the preference with confidence = 1.

This ensures preferences stabilize over time and don't flip on a single session's anomaly.

Step 3: Write Updated Preferences

Update ~/.claude/project-finisher-data/workflow_preferences.md with the new values.

---

workflow_preferences.md Format

# Workflow Preferences

_Auto-generated by project-finisher evolve skill. Last updated: YYYY-MM-DD_
_Total sessions observed: N_

## Pacing

- **Style**: fast | deliberate | mixed
- **Confidence**: N (number of agreeing observations)
- **Signals**: <summary of evidence>
- **Adaptation**: <what the orchestrator should do differently>

## Depth

- **Style**: shallow | deep | mixed
- **Confidence**: N
- **Signals**: <summary of evidence>
- **Adaptation**: <what the orchestrator should do differently>

## Workflow Ordering

- **Preferred sequence**: <e.g., "brainstorm(light) → execute → review" or "full 4-phase">
- **Phases typically skipped**: <list>
- **Confidence**: N
- **Adaptation**: <what the orchestrator should do differently>

## Tool Preferences

- **Agent vs direct**: prefer-direct | prefer-agents | mixed
- **Edit vs Write**: prefer-edit | prefer-write | mixed
- **Top 5 tools by frequency**: <list with counts>
- **Confidence**: N
- **Adaptation**: <what the orchestrator should do differently>

## Edit Size

- **Style**: incremental | large-rewrite | mixed
- **Confidence**: N
- **Signals**: <summary of evidence>
- **Adaptation**: <what the orchestrator should do differently>

## Error Recovery

- **Style**: retry | investigate | mixed
- **Confidence**: N
- **Signals**: <summary of evidence>
- **Adaptation**: <what the orchestrator should do differently>

## Interaction Patterns

- **Style**: cautious | direct | mixed
- **Confidence**: N
- **Signals**: <summary of evidence>
- **Adaptation**: <what the orchestrator should do differently>

## Session Log

| Date | Pacing | Depth | Workflow | Notes |
|------|--------|-------|----------|-------|
| YYYY-MM-DD | fast | shallow | skipped brainstorm | first observation |

---

Apply Procedure

When the orchestrator starts a new milestone, read workflow_preferences.md and apply these adaptations:

Pacing Adaptations

Preference	Orchestrator Behavior
fast	Limit brainstorming to 2 rounds max. Skip confirmation prompts. Compress Review phase to bullet points. Prefer action over discussion.
deliberate	Run full multi-round brainstorming. Include tradeoff discussions. Provide detailed review summaries.
mixed	Default behavior — no adaptation.

Depth Adaptations

Preference	Orchestrator Behavior
shallow	Lead with code and file changes. Minimize prose. Skip rationale unless asked. Brainstorm outputs should be bullet lists, not paragraphs.
deep	Include rationale for decisions. Discuss alternatives considered. Reference prior lessons explicitly. Brainstorm outputs can be detailed.
mixed	Default behavior.

Workflow Ordering Adaptations

Preference	Orchestrator Behavior
Phases consistently skipped	Reduce those phases to lightweight versions (1-2 bullets) rather than eliminating entirely.
Reordered phases	Follow the user's preferred order, but warn if skipping a phase creates risk for the current milestone.
Full 4-phase	No adaptation — follow standard workflow.

Tool Preference Adaptations

Preference	Orchestrator Behavior
prefer-direct	Use Grep/Glob/Read directly instead of spawning Agent subagents.
prefer-agents	Delegate research and exploration to Agent subagents.
prefer-edit	Use Edit for file modifications. Avoid full Write unless creating new files.
prefer-write	Use Write for file modifications when changes are extensive.

Edit Size Adaptations

Preference	Orchestrator Behavior
incremental	Use Edit tool for targeted changes. Break large modifications into multiple small edits. Avoid full file rewrites.
large-rewrite	Use Write tool for comprehensive changes. Batch related modifications into single operations.
mixed	Default behavior — choose Edit vs Write based on change scope.

Error Recovery Adaptations

Preference	Orchestrator Behavior
retry	On execution errors, try alternative approaches quickly. Minimize diagnostic steps.
investigate	On execution errors, read error output carefully. Check related files before retrying.
mixed	Default behavior — adapt error recovery to context.

Interaction Pattern Adaptations

Preference	Orchestrator Behavior
cautious	Always read files before editing. Explore surrounding code for context. Include related file reads in plans.
direct	Read only the target file before editing. Skip exploratory reads unless blocked.
mixed	Default behavior — read as needed.

Reviewer Rubric Weight Derivation

When updating workflow_preferences.md (Step 3), also recompute the "Reviewer Rubric Weights" section. These weights are derived deterministically from pacing and depth preferences:

Dimension	fast	deliberate	mixed
Test coverage	2	4	3
Lines changed	4	2	3
New dependencies	3	1	2

Dimension	shallow	deep	mixed
Test coverage	2	4	3
Code documentation	1	4	2
Architectural cleanliness	2	4	3

"Criteria met" is always weight 5 — it is the primary factor regardless of user style.

When both pacing and depth contribute to a dimension (e.g., test coverage), use the higher of the two values.

Example: A user with pacing=fast, depth=shallow would get:

• Criteria met: 5 (fixed)
• Test coverage: max(2, 2) = 2
• Lines changed: 4 (from fast)
• New dependencies: 3 (from fast)
• Code documentation: 1 (from shallow)
• Architectural cleanliness: 2 (from shallow)

This user's reviewer would strongly favor simpler, smaller implementations. A deliberate+deep user would favor thoroughness and clean architecture.

---

Initialization

If workflow_preferences.md does not exist, create it with all preferences set to mixed and confidence = 0. The system starts neutral and learns from observations.

---

Reset

If the user asks to reset preferences:

1. Archive the current workflow_preferences.md to workflow_preferences.YYYY-MM-DD.bak.md
2. Create a fresh file with all preferences at mixed / confidence 0
3. Optionally clear behavior_log.jsonl