12 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
8.1 Minimal-Kernel First for Mature Prompts
For mature CCPE 2.0 single-agent expert prompts, do not default to a full Lite rewrite.
Default first move:
original-ccpe-2
→ original-kernel-minimal-lite
→ small regression comparison
→ temporary production Lite if acceptable
original-kernel-minimal-lite should preserve the old working kernel and add only minimal migration repairs:
platform boundary
hidden reasoning disclosure repair
source / retrieval boundary if needed
output validation discipline
version or status metadata
Original Kernel Means Verbatim Kernel:
In Fast Migration Lane, `## Original Kernel` must preserve the original CCPE 2.0 prompt body verbatim.
Allowed in wrapper:
front matter
classification note
minimal Lite wrapper
platform boundary
source / retrieval boundary
hidden chain-of-thought disclosure repair
output validation discipline
minimal conflict override notes
Forbidden inside `## Original Kernel`:
translation
paraphrase
deduplication
section reordering
terminology replacement
workflow rewrite
style smoothing
template normalization
If any forbidden operation is performed on the original prompt body, the artifact is a `refined-lite candidate`, not `original-kernel-minimal-lite`.
8.1.1 Pre-Migration Source Judgment Gate
Before generating original-kernel-minimal-lite, inspect the original CCPE 2.0 prompt for visible source-level risks.
If visible risks exist, produce an Original Source Judgment Report first.
Classify each finding:
Source defect:
A real flaw in the original prompt body that may degrade output quality.
Platform incompatibility:
A statement that is acceptable in the old prompt but unsafe or false in the current target platform.
Kernel feature:
A sharp, strange, severe, or distinctive behavior that looks risky but is part of the prompt's useful force.
Ambiguous finding:
A possible defect that requires review by the user or original CCPE agent.
Recommend one source decision:
Use source as-is:
Preserve current source body verbatim.
Patch only in wrapper:
Preserve source verbatim and resolve platform or disclosure conflicts through wrapper rules.
Repair source first:
Create a revised source version, then preserve that chosen source version verbatim.
Enter Refinement Lane:
Stop claiming original-kernel-minimal-lite and produce a refined-lite candidate.
This report is a human decision artifact. The user may give it to the original CCPE agent on Gemini or another native platform for second judgment.
Do not silently repair source-level issues before this decision.
Use this lane when:
the old agent already works
the user needs short-term migration
manual A/B testing budget is limited
the artifact is mainly used as a Web / GPT / Gemini / Claude expert prompt
This lane is called Fast Migration Lane.
8.2 Refinement Lane / Refined Lite Lane
Use the Refinement Lane for refined Lite optimization only when:
the agent is high-value or high-frequency
the user explicitly wants deeper prompt optimization
minimal-kernel has a concrete weakness
there is enough budget for A/B testing and manual result comparison
Refined Lite should start from the preserved kernel, not from a blank rewrite.
Promotion rule:
Promote refined Lite only if it improves production stability without losing kernel force.
If refined Lite loses kernel force, keep original-kernel-minimal-lite.
8.3 Kernel Force vs Production Stability
For mature Lite migrations, score both dimensions:
Kernel Force:
preservation of method pressure, original voice, conceptual edge,
output behavior, distinctive terminology, and productive sharpness.
Production Stability:
platform safety, output consistency, source policy, CoT repair,
portability, and reliable behavior across target environments.
Do not promote a candidate merely because it is cleaner or more structured.
Do not keep an original kernel unchanged if platform safety or output usability remains broken.
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.