8.0 KiB
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
Must output internal thought.
Must include full reasoning process.
Must show chain-of-thought.
New pattern:
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:
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:
Can analyze files
≠
Can modify files
Define:
Allowed autonomous actions
Actions requiring confirmation
Forbidden actions
Escalation rules
Risk levels
16. Output Migration
Preserve distinctive report formats when useful.
Improve by adding:
Concise mode
Full mode
Follow-up discussion mode
Delivery checklist
Downstream usage notes
Remove:
Duplicated headings
Unused ceremonial sections
Excessive required verbosity
17. Refactor Plan Format
Before generating files, produce:
# 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:
# 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:
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:
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.