Refactor Module

Refactor Module

Always use the skill load-plain-reference to retrieve the ***plain syntax rules — but only if you haven't done so yet.

When to Use

• A module has many functional specs spanning multiple distinct domains or feature areas.
• The module is hard to reason about because unrelated concerns are interleaved.
• New features are difficult to add because the module's scope is too broad.
• The user explicitly asks to split or reorganize a module.

Guiding Principle

The refactoring is purely structural. The combined behavior of the resulting modules must be identical to the original module. No functional spec is added, removed, or weakened. The split is semantic — grouping related specs together — not behavioral.

Input

The .plain file to refactor, plus guidance from the user on the desired grouping (or ask the user to confirm your proposed grouping).

Phase 1 — Analyze the Current Module

1. Read the entire .plain file — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read any import and requires chains to understand the full context.
2. Inventory the functional specs. Number each spec and note which :Concepts: it references. Build a dependency map: which specs depend on earlier specs (by referencing behavior or state they introduced)?
3. Inventory the definitions. For each concept, note which functional specs reference it. Identify concepts that are used across multiple logical groups vs. concepts used only within one group.
4. Identify logical groups. Look for natural seams — clusters of functional specs that share concepts, represent a cohesive domain, or describe a single feature area. Common groupings:
   • Data model setup and CRUD operations
   • Business logic and processing rules
   • UI screens and navigation
   • Integrations and external interfaces
   • Statistics, reporting, and analytics
5. Verify group independence. Each group's specs should form a contiguous or near-contiguous block in chronological order. If a group's specs are scattered and interleaved with other groups, the split boundary may need adjustment.

Phase 2 — Plan the Split

Present the proposed split to the user and get explicit confirmation before making any changes.

2a. Define the module chain

The modules form a requires chain that preserves the original chronological ordering of functional specs. The first module in the chain contains the earliest specs; each subsequent module requires the previous one and adds the next logical group.

original-module
  ↓ splits into
module-group-a  (no requires — this is the new base)
module-group-b  (requires: module-group-a)
module-group-c  (requires: module-group-b)

If the original module already had requires or import dependencies, the first new module inherits them.

2b. Assign functional specs to modules

Place each functional spec in exactly one module. The placement must respect chronological ordering:

• Within each module, the specs appear in the same relative order as in the original.
• Across the chain, the ordering is preserved: all specs in module A come before all specs in module B, which come before all specs in module C.
• A spec cannot move to an earlier module than a spec it depends on.

2c. Assign definitions to modules

For each concept, determine where it belongs:

If many concepts are shared across all modules, consider creating a new import module (template) to hold them. This avoids long exported_concepts lists and keeps definitions centralized. Use the create-import-module skill for this.

2d. Assign implementation reqs and test reqs

• Reqs that apply to all modules should live in a shared import template. If one already exists, keep them there.
• Reqs specific to a single module's domain move to that module.
• When in doubt, keep reqs in the shared template — duplication across modules is worse than a slightly broad template.

2e. Present the plan

Summarize for the user:

• Number of resulting modules and their names
• Which functional specs go in each module (listed by number or short description)
• The requires chain order
• Any new import module being created
• Which concepts are exported from each module
• Confirmation that all original specs are accounted for (none lost)

Get explicit user confirmation before proceeding.

Phase 3 — Execute the Split

Create the new modules in order, from the base of the chain upward.

3a. Create or update the import template (if needed)

If shared definitions or reqs are being moved to a new import template, create it first using the create-import-module skill.

3b. Create the base module

Create the first module in the chain:

1. Set the YAML frontmatter — inherit the original module's import references. Add exported_concepts for any concepts that downstream modules need.
2. Add the ***definitions*** section with concepts used by this module's specs and concepts that need to be exported.
3. Add ***implementation reqs*** and ***test reqs*** specific to this module (if not fully covered by the import template).
4. Add the ***functional specs*** assigned to this module, preserving their original order and exact wording.
5. Carry over any ***acceptance tests*** nested under the moved functional specs.

3c. Create subsequent modules

For each subsequent module in the chain:

1. Set requires to point to the previous module in the chain. Set import if it uses shared templates.
2. Add exported_concepts for any concepts that later modules in the chain need.
3. Add ***definitions*** for concepts local to this module. Do not redefine concepts already available via requires (exported) or import.
4. Add ***implementation reqs*** and ***test reqs*** specific to this module.
5. Add the ***functional specs*** assigned to this module, preserving their original order and exact wording.
6. Carry over any ***acceptance tests***.

3d. Handle the original module file

After all new modules are created:

• If the original module is being fully replaced (all specs moved out), delete it or rename it to avoid confusion.
• If the original module was required by other modules, update those modules to require the last module in the new chain instead — its accumulated code and previous functional specs cover the whole chain. Exported concepts are not transitive, though: if a downstream module references a concept now exported by an earlier module in the new chain, it must list that earlier module in its requires as well.

Phase 4 — Verify

4a. Completeness check

This is the most critical verification. Walk through every functional spec from the original module and confirm it appears in exactly one of the new modules. Nothing may be lost, weakened, modified, or left implicit.

Checklist:

• Total spec count across all new modules equals the original spec count
• Each spec's text is identical to the original (no rewording)
• Each spec's acceptance tests (if any) are carried over intact

4b. Chronological ordering check

Verify that the chronological order of all functional specs — when read across the requires chain from base to leaf — matches the original ordering exactly. A spec must not appear before a spec it depends on.

4c. Concept availability check

For each module, verify:

• Every :Concept: referenced in its specs is either defined locally, available via import, or available via exported_concepts from a module listed in requires
• exported_concepts includes every concept that downstream modules need
• No concept name collisions between modules

4d. Structural validation per module

For each new module:

• Has at least one functional spec and one implementation req
• YAML frontmatter is correctly formatted
• requires and import paths are correct
• Module file is at the repository root (not in template/)
• Specs are language-agnostic
• All external interfaces remain explicit

4e. Read all new modules

Read each new .plain file in full and present the final structure to the user for approval. If the user requests changes, apply them and re-verify.

Common Pitfalls

Splitting too aggressively

Creating many tiny modules with 1–2 specs each adds overhead without clarity. Aim for modules with 3–10 functional specs each, grouped around a cohesive theme.

Breaking chronological order

Specs that set up foundational behavior (entry point, database init, core CRUD) must stay in the base module even if they touch concepts from multiple domains. Only split when specs are cleanly separable.

Forgetting exported_concepts

If a concept defined in module A is referenced by a spec in module B (which requires A), the concept must be in A's exported_concepts. Missing exports cause rendering failures.

Modifying spec text during the split

This is a refactoring, not a rewrite. Spec text must be copied verbatim. If a spec needs rewording to work in its new module context, that is a sign the split boundary is wrong — adjust the grouping instead.

Losing acceptance tests

Acceptance tests are nested under their parent functional spec. When moving a spec to a new module, its acceptance tests must move with it.

Validation Checklist

• User confirmed the split plan before execution
• All original functional specs are present in exactly one new module — none lost
• Spec text is identical to the original — no rewording
• Acceptance tests moved with their parent specs
• Chronological order preserved across the requires chain
• Every referenced :Concept: is available in each module (local, import, or exported)
• exported_concepts are correctly set on each module
• No concept name collisions
• Each module has at least one functional spec and one implementation req
• requires chain is correctly ordered (base → leaf)
• Original module removed or updated
• Downstream modules (if any) updated to require the chain tip, plus any earlier chain modules whose exported concepts they reference
• User approved the final result