file-structure-optimization

name	file-structure-optimization
description	Use for designing and maintaining repository file structure for clarity, modularity, discoverability, and low-duplication across app and documentation surfaces.

File Structure Optimization

Quick Index (Action-Routed)

Read First (All Actions)

1. Mission
2. Use This Skill When
3. Scope Boundary
4. Core Principles

Action Modules (Read As Needed)

1. Structural assessment:
   • Structure Audit
   • Smell Detection
2. Refactoring strategy:
   • Normalization Rules
   • Migration Safety Rules
3. Long-term hygiene:
   • Ownership and Boundaries
   • Acceptance Checklist

Output

1. Deliverable Format
2. Anti-Patterns

Mission

Keep repository layout predictable, modular, and easy to navigate while minimizing duplication and stale artifacts.

Use This Skill When

1. adding major features introducing new directories/files
2. repo navigation or discoverability has become difficult
3. duplicate or near-duplicate files are accumulating
4. refactors require moving modules, docs, or scripts
5. monorepo boundaries are unclear or leaking responsibilities

Scope Boundary

This skill governs filesystem information architecture and structural hygiene.

Use Doc Maintenance and File Maintenance for:

1. content-level documentation correctness and lifecycle maintenance

Use Order of Operations for:

1. dependency-safe execution order for moves/renames

Core Principles

1. organize by stable domain boundaries, not temporary implementation details
2. one canonical home per concern
3. explicit boundaries between app code, tooling, tests, docs, and generated artifacts
4. minimize path depth for high-frequency files
5. prevent duplicated truth sources

Structure Audit

Evaluate current structure for:

1. discoverability of core app entrypoints
2. cohesion of modules inside each directory
3. coupling/leakage across domains
4. duplicate docs/scripts/config fragments
5. dead or orphaned files

Smell Detection

Flag these smells:

1. multiple directories claiming same ownership domain
2. files named with vague terms (misc, temp, new2, copy-final)
3. deeply nested directories with single-child chains
4. duplicated docs differing by small stale edits
5. generated files mixed with hand-edited source without clear separation

Normalization Rules

1. define top-level directory purposes explicitly
2. separate source, tests, docs, tooling, and build artifacts
3. keep naming conventions consistent across sibling paths
4. co-locate files that change together
5. centralize shared utilities instead of cloning copies

Migration Safety Rules

1. batch moves by domain and keep PR scope legible
2. update imports, references, and docs in same change
3. preserve history with rename/move-aware operations where possible
4. validate commands, tests, and CI paths after moves
5. capture temporary compatibility shims only when necessary and time-bound

Ownership and Boundaries

1. define directory ownership or steward role for critical areas
2. maintain clear public/internal module boundaries
3. document canonical paths for runbooks and policy artifacts
4. treat structure drift as maintenance debt with explicit remediation

Acceptance Checklist

1. each top-level directory has a clear purpose
2. duplicate/stale artifacts are removed or consolidated
3. references/imports/docs updated to new paths
4. structure supports fast onboarding and maintenance
5. no orphaned files remain from migration

Deliverable Format

When applying this skill, provide:

1. structure audit findings
2. proposed/implemented directory map
3. files moved/merged/removed summary
4. validation results for references and tooling
5. residual cleanup backlog

Source Reference

Primary references:

1. Apple modular code organization guidance:
   • https://developer.apple.com/documentation/xcode/organizing-your-code-with-local-packages
2. Google engineering consistency/style guidance:
   • https://google.github.io/styleguide/
3. MIT software construction modularity and abstraction principles:
   • https://ocw.mit.edu/courses/6-005-software-construction-spring-2016/

Anti-Patterns

1. organizing primarily by framework internals over domain purpose
2. preserving duplicate files "just in case" without ownership
3. mixing generated and source artifacts without boundaries
4. moving files without synchronized reference/doc updates
5. deep nesting that hides high-traffic files

Related Skills

• Order of Operations: sequence structural changes safely.
• Regression Prevention: validate no behavior regressions during structural refactors.
• Doc Maintenance: keep structural docs aligned with moves.
• File Maintenance: sustain structure quality through ongoing audits.