# 2687 Integration Guide 5ecf84e2 > Process Evolution: Integration Guide - Skill: `tools-only/2687-integration-guide-5ecf84e2` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/2687-integration-guide-5ecf84e2` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/2687-integration-guide-5ecf84e2/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/tools-only/2687-integration-guide-5ecf84e2 --- # Process Evolution: Integration Guide How to implement continuous process improvement in a companion project. --- ## Implementing /record The `/record` command captures a session-level observation about what could be improved. It should be fast and low-friction. ### Command Definition ```markdown # /record Capture an observation about what could be improved in the companion's process. ## Steps 1. Ask the user: "What happened that could have gone better?" - Listen to the full description. - If the user is vague ("the session felt slow"), push for specificity: "Which part felt slow? Was it a specific command, a waiting period, or something about the flow?" 2. Structure the observation: **What happened:** [The specific situation] **What was expected:** [What should have happened] **What actually happened:** [The gap] **Affected component:** [Command name, skill name, protocol name, or "workflow"] **Suggested fix:** [Optional — the user may not know the fix] 3. Show the structured observation to the user for confirmation. 4. On confirmation, append to `tracking/session-records.md`. 5. Check record count: - If 5+ unprocessed records exist: "There are [N] unprocessed session records. Consider running /evolve to analyze patterns and propose improvements." ## Rules - This should take under 2 minutes. Do not turn it into a deep analysis. - Capture the observation as the user describes it — do not reframe or minimize. - If the user names a fix, record it as a suggestion, not a decision. /evolve will evaluate suggestions alongside other records. ``` ### Multiple Records Per Session Sometimes a session surfaces multiple observations. The `/record` command should handle this: ```markdown ## Variant: Multiple Records If the user has several observations: 1. Capture each one with the standard structure. 2. Write all to session-records.md in a single batch. 3. Do NOT combine them into one record — each observation is distinct. ``` --- ## Structuring Evolution Records ### File Location ``` tracking/session-records.md ``` ### File Structure ```markdown # Session Records ## Unprocessed ### [Date] — [Brief title] **What happened:** [The specific situation] **What was expected:** [What should have happened] **What actually happened:** [The gap] **Affected component:** [Command/skill/protocol name] **Suggested fix:** [Optional user suggestion] ### [Date] — [Brief title] ... ## Processed ### [Date] — [Brief title] [Original record] **Processed by:** /evolve on [date] **Outcome:** [What change was made, or "Deferred — waiting for pattern confirmation"] ``` ### Example Records ```markdown ### 2026-02-15 — /status reads stale insights **What happened:** /status reported the project state but did not mention recent insights. **What was expected:** The status report should surface relevant insights from the last 2-3 sessions. **What actually happened:** Had to manually open the insights log to find what was captured last time. **Affected component:** /status command **Suggested fix:** Add a step to /status that reads the insights log and surfaces recent entries. ### 2026-02-18 — /seed prompts too generic **What happened:** /seed generated a writing prompt that could apply to any writer. **What was expected:** The prompt should incorporate the writer's specific development focus from the craft assessment. **What actually happened:** Prompt said "Write a scene with dialogue." No mention of the writer's dialogue naturalism work. **Affected component:** /seed command **Suggested fix:** /seed should read the craft assessment and weight the prompt toward the current development focus. ### 2026-02-20 — /seed prompts still generic **What happened:** Second time /seed produced a prompt without referencing the writer's specific situation. **What was expected:** After last record, expected this would be addressed. **What actually happened:** Same issue as 2/18. **Affected component:** /seed command **Suggested fix:** Same as before — this is now a pattern. ``` --- ## Implementing /evolve The `/evolve` command analyzes accumulated records and proposes concrete changes. ### Command Definition ```markdown # /evolve Analyze session records and propose improvements to the companion's process. ## Steps 1. Read all records: - `tracking/session-records.md` (unprocessed section) - If fewer than 3 unprocessed records, inform the user: "Only [N] unprocessed records. /evolve works best with 5+ records so patterns can emerge. Continue recording, or proceed anyway?" 2. Identify patterns: - Group records by affected component. - Look for recurring themes (same component, similar complaint). - Apply the three-occurrence rule: single occurrences are noted but not acted on. Three or more occurrences are actionable patterns. - Note any suggested fixes that appear across multiple records. 3. For each actionable pattern, draft a proposal: **Pattern:** [Description of the recurring issue] **Records:** [References to the specific records that form this pattern] **Affected component:** [What needs to change] **Proposed change:** - **Before:** [Current behavior — show the relevant section of the command/skill] - **After:** [Proposed behavior — show the modified section] - **Rationale:** [Why this change addresses the pattern] - **Risk:** [What could go wrong, if anything] 4. For single-occurrence records: - Note them as "Monitoring — waiting for pattern confirmation" - Do NOT propose changes based on single occurrences (unless critical) 5. Present all proposals to the user: - Actionable patterns with specific proposed changes - Monitoring items (acknowledged but not acted on yet) - Ask: "Which proposals should I implement?" 6. For approved proposals: a. Read the current version of the affected file. b. Make the specific change described in the proposal. c. Show the user the diff (before/after). d. On confirmation, write the change. e. Commit with a clear message: "Evolve [component]: [brief description of change] Pattern: [what was recurring] Records: [dates of records that informed this]" 7. Move processed records to the "Processed" section of session-records.md with a reference to the outcome. ## Rules - Never implement a change without showing the before/after. - Never implement a change the user has not approved. - Make the SMALLEST change that addresses the pattern. Do not rewrite entire commands when a single step needs modification. - If a pattern suggests a new command or skill is needed, propose it but do not create it in /evolve. Create it as a separate task. ``` --- ## Evaluating Proposed Changes ### The Before/After Test Every proposed change should pass the before/after test: can you show the user exactly what changes and why? **Good proposal:** ``` Before: /status reads context files and reports state. After: /status reads context files AND insights log, reports state with recent insights highlighted. Why: Three records (2/15, 2/18, 2/22) report that /status does not surface insights, requiring manual log reading. ``` **Bad proposal:** ``` We should make /status better at surfacing context. Why: It doesn't feel comprehensive enough. ``` ### Risk Assessment Consider what could go wrong: - **Performance:** Does the change make the command slower? (Adding more file reads) - **Scope creep:** Does the change make the command try to do too much? - **Dependency:** Does the change create a new dependency that might break? - **Regression:** Could this change break something that currently works? Low-risk changes (adding a file read, reordering steps) can be approved quickly. High-risk changes (new commands, structural changes) deserve more discussion. ### Testing the Change After implementing a change, the next session that uses the affected command is the test. The session should verify: - Did the change address the pattern? - Did the change introduce new problems? - Does the command still feel right to use? If the change does not help or causes new issues, record that observation and consider reverting. --- ## The Three-Phase Methodology Applied to Process Process evolution follows the same three-phase pattern as the companion's primary work. ### Seeding: Accumulate Records The first 5-10 sessions with any companion are seeding for process evolution. Commands are used as-is, and observations are recorded. The goal is raw material — enough records to see patterns. **Do not** run /evolve during the first 3-5 sessions. Let patterns emerge naturally. ### Cultivation: Identify Patterns Once 5+ records have accumulated, /evolve can identify patterns. This is the cultivation phase — connecting observations, finding recurring themes, proposing changes. **Run /evolve** every 5-10 sessions or when records hit 5+ entries. ### Shaping: Implement Changes Approved proposals are implemented — commands are updated, skills are refined, protocols are adjusted. The companion's configuration becomes better adapted to the actual work. **After changes**, return to seeding: use the evolved commands and record new observations. --- ## Integrating /record with Session End The most natural time to run `/record` is at the end of a session, as part of the finish protocol. ### Pattern: Record Prompt in /checkpoint or /harvest ```markdown ## Step N: Process Observation Before closing, ask: "Was there anything about today's session that could have gone better? A command that felt awkward, a step that was missing, something that took too long?" If the user has an observation: - Capture it with the /record structure. - Append to tracking/session-records.md. If the user says "nothing" or "it was fine": - Move on. Do not force it. If unprocessed record count >= 5: - Note: "There are [N] unprocessed session records. Consider running /evolve next session." ``` ### Pattern: Mid-Session Record Sometimes the user notices an issue mid-session. The companion should offer to capture it immediately: ```markdown User: "This is annoying — the /seed command doesn't use my craft assessment." Companion: "Want me to record that as a process observation? It'll go into the session records for the next /evolve run." User: "Yes." [Capture the record immediately, then continue the session.] ``` --- ## When to Run /evolve ### By Record Count The simplest trigger: run /evolve when 5 or more unprocessed records exist. The /status or /checkpoint command should surface this count. ### By Session Count If sessions are frequent and records accumulate slowly, run /evolve every 10 sessions regardless of record count. Even 2-3 records after 10 sessions may contain patterns. ### By User Request The user can always invoke /evolve directly. They may notice a pattern before the companion does. ### Avoid - Running /evolve every session (too frequent, not enough data) - Running /evolve with only 1 record (not enough for patterns) - Never running /evolve (records accumulate but nothing changes) --- ## Common Pitfalls ### Record Fatigue If the user feels like /record is a chore, the friction is too high. Reduce it: offer a one-sentence capture option instead of the full structure. A brief note is better than no note. ### Over-Evolution Changing too many things at once makes it impossible to know what helped. Implement 1-3 changes per /evolve cycle, then observe. If everything changes at once, the next round of records cannot attribute problems to specific changes. ### Under-Evolution Accumulating records but never acting on them. The records become a complaint box that nobody empties. Set a hard trigger: when records hit 5, run /evolve. No exceptions. ### Evolving Without Evidence Changing a command because it "could be better" without any session records supporting the change. If it is not producing records, it is working well enough. Focus evolution where the evidence points. ### Losing the Git Trail Every evolution should be a clear git commit with rationale. If evolved commands are modified casually without commits, the history is lost and rollback becomes impossible.