Memory Informed Refactor

---
name: memory-informed-refactor
description: "Pre-refactor context briefing -- loads relevant prior decisions, failures, and pitfalls from Pensyve memory before refactoring a module. Use before any refactor to avoid repeating past mistakes."
---

# 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.

## When to Use

Invoke before refactoring any module, file, or component. Provides a structured briefing from memory so you start with full context.

## Instructions

### Step 1: Query Memory for Context

Normalize the target to a lowercase-hyphenated entity and pass it as `entity`
to every query. Run multiple `pensyve_recall` queries to gather comprehensive
context about the target within the shared recall budget:

1. **Direct matches**: `pensyve_recall` with query `"<target>"` (limit: 5)
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 2: Inspect the Entity

Call `pensyve_inspect` with `entity: "<target>"` and `limit: 20` to get up to 20
memories for that entity. The tool has no pagination, so do not describe this
sample as a complete inventory.

### Step 3: 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 4: 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 `["antigravity-cli", "<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

- 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, tell the user to open `/mcp` and authenticate Pensyve.
- If `pensyve_episode_start` fails when the user accepts tracking, report the error but do not block the refactor.