memory-informed-refactor

name	memory-informed-refactor
description	Pre-refactor context loading — queries Pensyve memory for past decisions, failures, and patterns related to a refactoring target, then compiles a briefing

Memory-Informed Refactor

Load historical context from Pensyve memory before starting a refactor. Surfaces past decisions, failed approaches, known pitfalls, and relevant patterns to avoid repeating mistakes.

Instructions

When this skill is invoked with a refactoring target, follow these steps:

Step 1: Identify the Target

The user should specify a module, file, or component to refactor (e.g., "auth-service", "database-layer", "api-routes"). If no target is provided, ask the user what they are refactoring before proceeding.

Step 2: Query Memory for Context

Run multiple pensyve_recall queries to gather comprehensive context about the target:

1. Direct matches: pensyve_recall with query "<target>" (limit: 10)
2. Refactor history: pensyve_recall with query "<target> refactor" (limit: 5)
3. Past failures: pensyve_recall with query "<target> failed" (limit: 5)
4. Past failures (alternate): pensyve_recall with query "<target> error" (limit: 5)
5. Design decisions: pensyve_recall with query "<target> decided" (limit: 5)
6. Dependencies: pensyve_recall with query "<target> depends" (limit: 5)

Step 3: Inspect the Entity

If the target matches an entity name, also call pensyve_inspect with entity: "<target>" to get the full memory inventory for that entity.

Step 4: Compile Briefing

Organize the findings into a structured briefing. Deduplicate results that appear across multiple queries.

Refactor Briefing: <target>

Known Facts

• List of semantic memories about the target, ordered by confidence
• Include confidence scores

Past Decisions

• Architecture or design decisions related to this target
• Include the reasoning if available ("chose X because Y")

Past Outcomes

• Previous refactoring attempts and their results
• Bug fixes and their root causes
• What worked and what did not

Known Pitfalls

• Failed approaches (flagged clearly so they are not repeated)
• Edge cases or gotchas discovered in past sessions
• Dependencies that may be affected

Procedural Knowledge

• Action-outcome patterns with reliability scores
• Proven workflows related to this target

Recommendations

• Synthesize the above into 2-5 actionable recommendations
• Flag any conflicts or contradictions in the memory

Memory Gaps

• Areas where no relevant memories exist
• Suggest what to watch for during the refactor

If no relevant memories are found for a section, omit that section entirely rather than showing an empty one. If no memories are found at all, say so clearly and proceed without historical context.

Step 5: Offer Episode Tracking

After presenting the briefing, offer to track the refactor as an episode:

Would you like me to track this refactor as an episode? This will let Pensyve capture the decisions and outcomes from this session for future reference.

If yes, I will call pensyve_episode_start with participants ["codex", "<target>"].

If the user accepts, call pensyve_episode_start. Remind the user to close the episode at the end of the refactor (or suggest using the session-memory skill).

Constraints

• All memory operations go through the Pensyve MCP tools exclusively. Do not read or write to the local filesystem for memory purposes.
• Do not fabricate or infer memories that are not in the query results. Only report what the MCP tools return.
• Present the briefing before any refactoring work begins. The purpose is to inform, not to act.
• Entity names MUST be lowercase and hyphenated.
• Do not start the refactor itself -- this skill only provides the briefing. The user decides when and how to proceed.
• If the MCP server returns errors, present whatever partial results were obtained and note which queries failed.

Error Handling

• If pensyve_recall returns errors on some queries, present results from the successful queries and note the failures.
• If pensyve_inspect fails, skip the entity inspection and rely on recall results.
• If the MCP server is not connected, inform the user and suggest checking their PENSYVE_API_KEY environment variable and MCP configuration.
• If pensyve_episode_start fails when the user accepts tracking, report the error but do not block the refactor.