ccpe-system/.codex/skills/ccpe-forge/references/refactor-mode.md

# Refactor Mode

## 1. Purpose

Refactor Mode upgrades, restructures, or migrates existing AI artifacts.

It is used after classification and audit.

Its purpose is not to make artifacts longer.

Its purpose is to improve:

```text
Clarity
Reuse
Maintainability
Portability
Safety
Evaluation
Model fidelity
Workflow reliability
```

while preserving the original intellectual force.

## 2. When to Use Refactor Mode

Use Refactor Mode when the user asks to:

```text
Upgrade an old CCPE 2.0 Agent
Repair an existing prompt
Convert a prompt into Agent Spec
Split an embedded model
Extract a reusable Skill
Prepare a workflow for Runtime
Prepare an artifact for Codex / Claude Code / OpenClaw
Create a portable Lite version
Migrate an old committee into Runtime structure
```

## 3. Refactor Mode Workflow

Follow this sequence:

```text
1. Audit first
2. Probe current and planned usage scenario
3. Define minimal target layers
4. Define target classification
5. Identify preserved elements
6. Identify extracted elements
7. Identify modified elements
8. Identify deprecated elements
9. Produce Refactor Plan
10. List target files
11. Ask for confirmation when required
12. Generate upgraded drafts
13. Validate against quality rubric
14. Produce Upgrade Report
```

## 3.1 Scenario Probe

For existing artifacts, determine:

```text
How is the artifact currently used?
Is it a Web / GPT / Gemini / Claude single-agent prompt?
Is the user manually coordinating it with other agents?
Is it already a committee member?
Does it need to be callable from Codex as a Skill?
Does it need a durable Agent Spec now, or only later?
Is Runtime needed now, or should it wait until the whole workflow is stable?
```

Scenario probe controls extraction. Do not produce Agent, Skill, and Runtime layers just because they are possible.

## 4. Audit First Rule

Do not refactor blindly.

Before rewriting, establish:

```text
Original classification
Target classification
Embedded components
Operating mode
Depth vs automation orientation
Model extraction need
Skill extraction need
Runtime need
Human decision points
```

## 5. Preservation Rule

Preserve:

```text
Original objective
Core metaphor
Cognitive stance
Distinctive terminology
Reasoning style
Domain worldview
Useful severity
Output structure when valuable
Model assumptions
Model mechanism
Falsification boundary
User's intellectual intent
```

Do not flatten original thinking into generic assistant language.

Do not remove metaphor when metaphor carries structural meaning.

Do not polish away conceptual tension.

## 6. Improvement Rule

Improve:

```text
Objective clarity
Input/output contract
Layer separation
Model separation
Skill reusability
Authority boundaries
Workflow coherence
State handling
Evaluation criteria
Runtime safety
Portability
Version metadata
```

## 7. Component Extraction

When an artifact is hybrid, consider extracting components.

Possible outputs:

```text
Portable Lite Prompt
Agent Spec
Skill Spec
Runtime Spec
Model Card
Model Index Entry
Upgrade Report
```

## 8. When to Keep a Lite Version

Keep a portable Lite version when:

```text
The artifact is used in Custom GPT / Gemini / Claude chat.
One-piece deployment matters.
The user wants quick direct usage.
The embedded model is needed for portability.
External references may not be available.
```

Lite version may contain compressed model content.

For mature single-agent expert prompts, Lite is the default production artifact. Preserve the original CCPE 2.0 four-layer working kernel when that kernel is part of the prompt's effect.

Recommended initial migration:

```text
Original mature prompt
→ Lite preserving working behavior
→ Model Card if model is stable
→ Regression comparison against original output
→ Additional Skill / Agent / Runtime only if scenario requires it
```

## 9. When to Extract Model Card

Extract a Model Card when:

```text
The model is reusable.
The model is user-authored or conceptually important.
The model appears in multiple artifacts.
The model has assumptions, mechanism, and scope.
The model should be indexed.
```

Model Card should preserve the model itself, not the Agent persona.

## 10. When to Extract Skill

Extract a Skill when:

```text
The method is repeatable.
The procedure has stable steps.
Multiple agents can use it.
It has definable input/output.
It can be validated.
It wraps tool use or method execution.
```

Skill should contain execution rules, not identity.

## 11. When to Create Agent Spec

Create Agent Spec when:

```text
The role is durable.
The role has responsibilities over time.
It participates in a workflow.
It calls Skills.
It needs collaboration rules.
It needs authority boundaries.
It needs evaluation criteria.
```

## 12. When to Create Runtime

Create Runtime when:

```text
Multiple stages are involved.
Multiple agents are involved.
There are handoffs.
There are human decision gates.
There is state to preserve.
Reports are collected or synthesized.
Tools or files are used.
The workflow may be repeated.
```

## 13. CoT Migration

Replace old chain-of-thought requirements.

Old pattern:

```text
Must output internal thought.
Must include full reasoning process.
Must show chain-of-thought.
```

New pattern:

```text
Perform internal analysis.
Output:
- reasoning summary
- assumptions
- decision criteria
- checks performed
- uncertainty notes
- validation result
```

Never require hidden chain-of-thought disclosure.

## 14. Source and Retrieval Migration

If the old artifact includes retrieval or online information, add Source Policy.

Specify:

```text
When retrieval is required
What retrieved material means
How source conflicts are handled
How uncertainty is marked
Whether retrieved material is raw data, evidence, or context
```

Do not treat retrieved material as automatically true.

## 15. Authority Migration

Separate capability from authority.

Example:

```text
Can analyze files
≠
Can modify files
```

Define:

```text
Allowed autonomous actions
Actions requiring confirmation
Forbidden actions
Escalation rules
Risk levels
```

## 16. Output Migration

Preserve distinctive report formats when useful.

Improve by adding:

```text
Concise mode
Full mode
Follow-up discussion mode
Delivery checklist
Downstream usage notes
```

Remove:

```text
Duplicated headings
Unused ceremonial sections
Excessive required verbosity
```

## 17. Refactor Plan Format

Before generating files, produce:

```md
# Refactor Plan

## 1. Original Artifact

## 2. Original Classification

## 3. Target Classification

## 4. Preserved Elements

## 5. Extracted Elements

## 6. Modified Elements

## 7. Deprecated Elements

## 8. Proposed Files

## 9. Human Confirmation Required

## 10. Validation Criteria
```

## 18. Upgrade Report Format

After generating files, produce:

```md
# CCPE Upgrade Report

## 1. Original Artifact
Name:
Path:
Version:
Original Format:

## 2. Original Classification
Primary:
Secondary Components:
Operating Mode:
Depth vs Automation:

## 3. Target Classification
Primary:
Secondary Outputs:
Runtime Need:

## 4. Preserved Elements

## 5. Extracted Elements

## 6. Modified Elements

## 7. Deprecated or Removed Elements

## 8. Generated Files

## 9. Model Index Updates

## 10. Human Decisions Required

## 11. Next Step
```

## 19. File Writing Policy

When writing files:

```text
Do not overwrite originals unless instructed.
Prefer workbench/upgraded/ for drafts.
Use canonical directories only after confirmation.
Use lowercase kebab-case filenames.
Include version metadata for durable artifacts.
```

## 20. Validation Checklist

Before finalizing, check:

```text
Did we preserve the original purpose?
Did we preserve the model's intellectual force?
Did we classify correctly?
Did we split only where useful?
Are output files coherent?
Are human decision gates clear?
Are evaluation rules present?
Is the artifact usable on the target platform?
```

## 21. Final Rule

Refactor Mode should make the artifact stronger, not sterile.

A good refactor is not a cleanup that erases the mind behind the artifact.

It is a structural upgrade that lets the original cognitive power travel farther.