Component Flattening Analysis

Component Flattening Analysis

This skill identifies component hierarchy issues and ensures components exist only as leaf nodes in directory/namespace structures, removing orphaned classes from root namespaces.

How to Use

Quick Start

Request analysis of your codebase:

• "Find orphaned classes in root namespaces"
• "Flatten component hierarchies"
• "Identify components that need flattening"
• "Analyze component structure for hierarchy issues"

Usage Examples

Example 1: Find Orphaned Classes

User: "Find orphaned classes in root namespaces"

The skill will:
1. Scan component namespaces for hierarchy issues
2. Identify orphaned classes in root namespaces
3. Detect components built on top of other components
4. Suggest flattening strategies
5. Create refactoring plan

Example 2: Flatten Components

User: "Flatten component hierarchies in this codebase"

The skill will:
1. Identify components with hierarchy issues
2. Analyze orphaned classes
3. Suggest consolidation or splitting strategies
4. Create refactoring plan
5. Estimate effort

Example 3: Component Structure Analysis

User: "Analyze component structure for hierarchy issues"

The skill will:
1. Map component namespace structure
2. Identify root namespaces with code
3. Find components built on components
4. Flag hierarchy violations
5. Provide recommendations

Step-by-Step Process

1. Scan Structure: Map component namespace hierarchies 2. Identify Issues: Find orphaned classes and component nesting 3. Analyze Options: Determine flattening strategy (consolidate vs split) 4. Create Plan: Generate refactoring plan with steps 5. Execute: Refactor components to remove hierarchy

When to Use

Apply this skill when:

• After gathering common domain components (Pattern 2)
• Before determining component dependencies (Pattern 4)
• When components have nested structures
• Finding orphaned classes in root namespaces
• Preparing for domain grouping
• Cleaning up component structure
• Ensuring components are leaf nodes only

Core Concepts

Component Definition

A component is identified by a leaf node in directory/namespace structure:

• Leaf Node: The deepest directory containing source files
• Component: Source code files in leaf node namespace
• Subdomain: Parent namespace that has been extended

Key Rule: Components exist only as leaf nodes. If a namespace is extended, the parent becomes a subdomain, not a component.

Root Namespace

A root namespace is a namespace node that has been extended:

• Extended: Another namespace node added below it
• Example: ss.survey extended to ss.survey.templates
• Result: ss.survey becomes a root namespace (subdomain)

Orphaned Classes

Orphaned classes are source files in root namespaces:

• Location: Root namespace (non-leaf node)
• Problem: No definable component associated with them
• Solution: Move to leaf node namespace (component)

Example:

ss.survey/              ← Root namespace (extended by .templates)
├── Survey.js           ← Orphaned class (in root namespace)
└── templates/          ← Component (leaf node)
    └── Template.js

Flattening Strategies

Strategy 1: Consolidate Down

• Move code from leaf nodes into root namespace
• Makes root namespace the component
• Example: Move ss.survey.templates → ss.survey

Strategy 2: Split Up

• Move code from root namespace into new leaf nodes
• Creates new components from root namespace
• Example: Split ss.survey → ss.survey.create + ss.survey.process

Strategy 3: Move Shared Code

• Move shared code to dedicated component
• Creates .shared component
• Example: ss.survey shared code → ss.survey.shared

Analysis Process

Phase 1: Map Component Structure

Scan directory/namespace structure to identify hierarchy:

1. Map Namespace Tree

• Build tree of all namespaces
• Identify parent-child relationships
• Mark leaf nodes (components)

2. Identify Root Namespaces

• Find namespaces that have been extended
• Mark as root namespaces (subdomains)
• Note which namespaces extend them

3. Locate Source Files

• Find all source files in each namespace
• Map files to their namespace location
• Identify files in root namespaces

Example Structure Mapping:

## Component Structure Map

ss.survey/ ← Root namespace (extended) ├── Survey.js ← Orphaned class ├── SurveyProcessor.js ← Orphaned class └── templates/ ← Component (leaf node) ├── EmailTemplate.js └── SMSTemplate.js

ss.ticket/ ← Root namespace (extended) ├── Ticket.js ← Orphaned class ├── assign/ ← Component (leaf node) │ └── TicketAssign.js └── route/ ← Component (leaf node) └── TicketRoute.js

Phase 2: Identify Orphaned Classes

Find source files in root namespaces:

1. Scan Root Namespaces

• Check each root namespace for source files
• Identify files that are orphaned
• Count orphaned files per root namespace

2. Classify Orphaned Classes

• Shared Code: Common utilities, interfaces, abstract classes
• Domain Code: Business logic that should be in component
• Mixed: Combination of shared and domain code

3. Assess Impact

• How many files are orphaned?
• What functionality do they contain?
• What components depend on them?

Example Orphaned Class Detection:

## Orphaned Classes Found

### Root Namespace: ss.survey

**Orphaned Files** (5 files):

- Survey.js (domain code - survey creation)
- SurveyProcessor.js (domain code - survey processing)
- SurveyValidator.js (shared code - validation)
- SurveyFormatter.js (shared code - formatting)
- SurveyConstants.js (shared code - constants)

**Classification**:

- Domain Code: 2 files (should be in components)
- Shared Code: 3 files (should be in .shared component)

**Dependencies**: Used by ss.survey.templates component

Phase 3: Analyze Flattening Options

Determine best flattening strategy for each root namespace:

1. Option 1: Consolidate Down

• Move leaf node code into root namespace
• Makes root namespace the component
• Use when: Leaf nodes are small, related functionality

2. Option 2: Split Up

• Move root namespace code into new leaf nodes
• Creates multiple components from root
• Use when: Root namespace has distinct functional areas

3. Option 3: Move Shared Code

• Extract shared code to .shared component
• Keep domain code in root or split
• Use when: Root namespace has shared utilities

Example Flattening Analysis:

## Flattening Options Analysis

### Root Namespace: ss.survey

**Current State**:

- Root namespace: 5 orphaned files
- Leaf component: ss.survey.templates (7 files)

**Option 1: Consolidate Down** ✅ Recommended

- Move templates code into ss.survey
- Result: Single component ss.survey
- Effort: Low (7 files to move)
- Rationale: Templates are small, related to survey functionality

**Option 2: Split Up**

- Create ss.survey.create (2 files)
- Create ss.survey.process (1 file)
- Create ss.survey.shared (3 files)
- Keep ss.survey.templates (7 files)
- Effort: High (multiple components to create)
- Rationale: More granular, but may be over-engineering

**Option 3: Move Shared Code**

- Create ss.survey.shared (3 shared files)
- Keep domain code in root (2 files)
- Keep ss.survey.templates (7 files)
- Effort: Medium
- Rationale: Separates shared from domain, but still has hierarchy

Phase 4: Create Flattening Plan

Generate refactoring plan for each root namespace:

1. Select Strategy

• Choose best flattening option
• Consider effort, complexity, maintainability

2. Plan Refactoring Steps

• List files to move
• Identify target namespaces
• Note dependencies to update

3. Estimate Effort

• Time to refactor
• Risk assessment
• Testing requirements

Example Flattening Plan:

## Flattening Plan

### Priority: High

**Root Namespace: ss.survey**

**Strategy**: Consolidate Down

**Steps**:

1. Move files from ss.survey.templates/ to ss.survey/
   - EmailTemplate.js
   - SMSTemplate.js
   - [5 more files]

2. Update imports in dependent components
   - Update references from ss.survey.templates._ to ss.survey._

3. Remove ss.survey.templates/ directory

4. Update namespace declarations
   - Change namespace from ss.survey.templates to ss.survey

5. Run tests to verify changes

**Effort**: 2-3 days
**Risk**: Low (templates are self-contained)
**Dependencies**: None

Phase 5: Execute Flattening

Perform the refactoring:

1. Move Files

• Move source files to target namespace
• Update file paths and imports

2. Update References

• Update imports in dependent components
• Update namespace declarations
• Update directory structure

3. Verify Changes

• Run tests
• Check for broken references
• Validate component structure

Output Format

Orphaned Classes Report

## Orphaned Classes Analysis

### Root Namespace: ss.survey

**Status**: ⚠️ Has Orphaned Classes

**Orphaned Files** (5 files):

- Survey.js (domain code)
- SurveyProcessor.js (domain code)
- SurveyValidator.js (shared code)
- SurveyFormatter.js (shared code)
- SurveyConstants.js (shared code)

**Leaf Components**:

- ss.survey.templates (7 files)

**Issue**: Root namespace contains code but is extended by leaf component

**Recommendation**: Consolidate templates into root namespace

Component Hierarchy Issues

## Component Hierarchy Issues

| Root Namespace | Orphaned Files | Leaf Components                 | Issue                | Recommendation   |
| -------------- | -------------- | ------------------------------- | -------------------- | ---------------- |
| ss.survey      | 5              | 1 (templates)                   | Has orphaned classes | Consolidate down |
| ss.ticket      | 45             | 2 (assign, route)               | Large orphaned code  | Split up         |
| ss.reporting   | 0              | 3 (tickets, experts, financial) | No issue             | ✅ OK            |

Flattening Plan

## Flattening Plan

### Priority: High

**ss.survey** → Consolidate Down

- Move 7 files from templates to root
- Effort: 2-3 days
- Risk: Low

### Priority: Medium

**ss.ticket** → Split Up

- Create ss.ticket.maintenance (30 files)
- Create ss.ticket.completion (10 files)
- Create ss.ticket.shared (5 files)
- Effort: 1 week
- Risk: Medium

Analysis Checklist

Structure Mapping:

• [ ] Mapped all namespace hierarchies
• [ ] Identified root namespaces
• [ ] Located all source files
• [ ] Marked leaf nodes (components)

Orphaned Class Detection:

• [ ] Scanned root namespaces for source files
• [ ] Identified orphaned classes
• [ ] Classified orphaned classes (shared/domain/mixed)
• [ ] Assessed impact and dependencies

Flattening Analysis:

• [ ] Analyzed consolidation option
• [ ] Analyzed splitting option
• [ ] Analyzed shared code extraction option
• [ ] Selected best strategy for each root namespace

Plan Creation:

• [ ] Selected flattening strategy
• [ ] Created refactoring steps
• [ ] Estimated effort and risk
• [ ] Prioritized work

Execution:

• [ ] Moved files to target namespaces
• [ ] Updated imports and references
• [ ] Updated namespace declarations
• [ ] Verified changes with tests

Implementation Notes

For Node.js/Express Applications

Components typically in services/ directory:

services/
├── survey/              ← Root namespace (extended)
│   ├── Survey.js       ← Orphaned class
│   └── templates/      ← Component (leaf node)
│       └── Template.js

Flattening:

• Consolidate: Move templates/ files to survey/
• Split: Create survey/create/ and survey/process/
• Shared: Create survey/shared/ for utilities

For Java Applications

Components identified by package structure:

com.company.survey       ← Root package (extended)
├── Survey.java         ← Orphaned class
└── templates/          ← Component (leaf package)
    └── Template.java

Flattening:

• Consolidate: Move templates classes to survey package
• Split: Create survey.create and survey.process packages
• Shared: Create survey.shared package

Detection Strategies

Find Root Namespaces with Code:

// Find root namespaces containing source files
function findRootNamespacesWithCode(namespaces, sourceFiles) {
  const rootNamespaces = namespaces.filter((ns) => {
    // Check if namespace has been extended
    const hasChildren = namespaces.some((n) => n.startsWith(ns + '.') || n.startsWith(ns + '/'))

    // Check if namespace contains source files
    const hasFiles = sourceFiles.some((f) => f.namespace === ns)

    return hasChildren && hasFiles
  })

  return rootNamespaces
}

Find Orphaned Classes:

// Find orphaned classes in root namespaces
function findOrphanedClasses(rootNamespaces, sourceFiles) {
  const orphaned = []

  rootNamespaces.forEach((rootNs) => {
    const files = sourceFiles.filter((f) => f.namespace === rootNs)
    orphaned.push({
      rootNamespace: rootNs,
      files: files,
      count: files.length,
    })
  })

  return orphaned
}

Fitness Functions

After flattening components, create automated checks:

No Source Code in Root Namespaces

// Alert if source code exists in root namespace
function checkRootNamespaceCode(namespaces, sourceFiles) {
  const violations = []

  namespaces.forEach((ns) => {
    // Check if namespace has been extended
    const hasChildren = namespaces.some((n) => n.startsWith(ns + '.') || n.startsWith(ns + '/'))

    if (hasChildren) {
      // Check if namespace contains source files
      const files = sourceFiles.filter((f) => f.namespace === ns)

      if (files.length > 0) {
        violations.push({
          namespace: ns,
          files: files.map((f) => f.name),
          issue: 'Root namespace contains source files (orphaned classes)',
        })
      }
    }
  })

  return violations
}

Components Only as Leaf Nodes

// Ensure components exist only as leaf nodes
function validateComponentStructure(namespaces, sourceFiles) {
  const violations = []

  // Find all leaf nodes (components)
  const leafNodes = namespaces.filter((ns) => {
    return !namespaces.some((n) => n.startsWith(ns + '.') || n.startsWith(ns + '/'))
  })

  // Check that all source files are in leaf nodes
  sourceFiles.forEach((file) => {
    if (!leafNodes.includes(file.namespace)) {
      violations.push({
        file: file.name,
        namespace: file.namespace,
        issue: 'Source file not in leaf node (component)',
      })
    }
  })

  return violations
}

Best Practices

Do's ✅

• Ensure components exist only as leaf nodes
• Remove orphaned classes from root namespaces
• Choose flattening strategy based on functionality
• Consolidate when functionality is related
• Split when functionality is distinct
• Extract shared code to .shared components
• Update all references after flattening
• Verify changes with tests

Don'ts ❌

• Don't leave orphaned classes in root namespaces
• Don't create components on top of other components
• Don't skip updating imports after moving files
• Don't flatten without analyzing impact
• Don't mix flattening strategies inconsistently
• Don't ignore shared code when flattening
• Don't skip testing after refactoring

Common Patterns

Pattern 1: Simple Consolidation

Before:

ss.survey/
├── Survey.js           ← Orphaned
└── templates/          ← Component
    └── Template.js

After:

ss.survey/              ← Component (leaf node)
├── Survey.js
└── Template.js

Pattern 2: Functional Split

Before:

ss.ticket/              ← Root namespace
├── Ticket.js           ← Orphaned (45 files)
├── assign/             ← Component
└── route/              ← Component

After:

ss.ticket/              ← Subdomain
├── maintenance/        ← Component
│   └── Ticket.js
├── completion/        ← Component
│   └── TicketCompletion.js
├── assign/             ← Component
└── route/              ← Component

Pattern 3: Shared Code Extraction

Before:

ss.survey/              ← Root namespace
├── Survey.js           ← Domain code
├── SurveyValidator.js  ← Shared code
└── templates/          ← Component

After:

ss.survey/              ← Component
├── Survey.js
└── shared/             ← Component
    └── SurveyValidator.js

Next Steps

After flattening components:

1. Apply Determine Component Dependencies Pattern - Analyze coupling 2. Create Component Domains - Group components into domains 3. Create Domain Services - Extract domains to services

Notes

• Components must exist only as leaf nodes
• Root namespaces with code are problematic
• Flattening improves component clarity
• Choose flattening strategy based on functionality
• Shared code should be in dedicated components
• Always update references after moving files
• Test thoroughly after flattening

Component Flattening Analysis - Quick Reference

Component Definition

Component = Leaf node in directory/namespace structure containing source files

Key Rule: Components exist only as leaf nodes. If namespace is extended, parent becomes subdomain.

Root Namespace vs Component

Orphaned Classes

Orphaned Class = Source file in root namespace (non-leaf node)

Problem: No definable component associated with it

Solution: Move to leaf node namespace (component)

Detection

Root namespace extended?
├─ YES → Check for source files
│   ├─ Has files? → Orphaned classes found
│   └─ No files? → ✅ OK
└─ NO → Not a root namespace

Flattening Strategies

Strategy 1: Consolidate Down ✅

When: Leaf nodes are small, related functionality

Action: Move leaf code into root namespace

Example:

Before: ss.survey/ + ss.survey.templates/
After:  ss.survey/ (single component)

Strategy 2: Split Up ✅

When: Root namespace has distinct functional areas

Action: Move root code into new leaf nodes

Example:

Before: ss.ticket/ (45 orphaned files)
After:  ss.ticket.maintenance/ + ss.ticket.completion/

Strategy 3: Extract Shared ✅

When: Root namespace has shared utilities

Action: Move shared code to .shared component

Example:

Before: ss.survey/ (domain + shared code)
After:  ss.survey/ + ss.survey.shared/

Decision Tree

Found orphaned classes?
├─ YES → Analyze functionality
│   ├─ Related to leaf components?
│   │   ├─ YES → Consolidate Down
│   │   └─ NO → Distinct areas?
│   │       ├─ YES → Split Up
│   │       └─ NO → Shared code?
│   │           └─ YES → Extract Shared
│   └─ NO → ✅ No action needed
└─ NO → ✅ Structure is flat

Common Patterns

Pattern 1: Simple Consolidation

Before:
ss.survey/
├── Survey.js           ← Orphaned
└── templates/         ← Component
    └── Template.js

After:
ss.survey/             ← Component
├── Survey.js
└── Template.js

Pattern 2: Functional Split

Before:
ss.ticket/             ← Root (45 orphaned files)
├── assign/            ← Component
└── route/              ← Component

After:
ss.ticket/             ← Subdomain
├── maintenance/       ← Component
├── completion/         ← Component
├── assign/            ← Component
└── route/              ← Component

Pattern 3: Shared Code Extraction

Before:
ss.survey/             ← Root
├── Survey.js          ← Domain
├── Validator.js       ← Shared
└── templates/         ← Component

After:
ss.survey/             ← Component
├── Survey.js
└── shared/            ← Component
    └── Validator.js

Quick Analysis Steps

1. Map → Build namespace tree, identify root namespaces 2. Detect → Find orphaned classes in root namespaces 3. Analyze → Determine flattening strategy 4. Plan → Create refactoring steps 5. Execute → Move files, update references

Output Template

## Orphaned Classes Analysis

### Root Namespace: [name]

**Orphaned Files** (X files):

- File1.js (domain/shared code)
- File2.js (domain/shared code)

**Leaf Components**:

- [component.name] (X files)

**Issue**: [description]

**Recommendation**: [strategy]

## Flattening Plan

### Priority: High/Medium/Low

**[Namespace]** → [Strategy]

- [Steps]
- Effort: X days
- Risk: Low/Medium/High

Validation Rules

Rule 1: Components Only as Leaf Nodes

✅ Valid:
ss.survey.templates/   ← Component (leaf node)

❌ Invalid:
ss.survey/             ← Root namespace with code
├── Survey.js          ← Orphaned class
└── templates/         ← Component

Rule 2: No Orphaned Classes

✅ Valid:
ss.survey/             ← Subdomain (no code)
└── templates/         ← Component (has code)
    └── Template.js

❌ Invalid:
ss.survey/             ← Root namespace
├── Survey.js          ← Orphaned class ❌
└── templates/         ← Component
    └── Template.js

Quick Checklist

• [ ] Mapped namespace hierarchies
• [ ] Identified root namespaces
• [ ] Found orphaned classes
• [ ] Classified orphaned classes
• [ ] Selected flattening strategy
• [ ] Created refactoring plan
• [ ] Updated all references
• [ ] Verified with tests

Component Flattening Analysis Skill

A skill for identifying and fixing component hierarchy issues by detecting orphaned classes in root namespaces and ensuring components exist only as leaf nodes.

What This Skill Does

This skill analyzes codebases to:

1. Map component structure to identify namespace hierarchies 2. Detect orphaned classes in root namespaces 3. Identify component nesting (components built on components) 4. Analyze flattening options (consolidate vs split vs extract shared) 5. Create flattening plans with refactoring steps 6. Ensure components are leaf nodes only 7. Remove hierarchy violations from component structure

When to Use This Skill

This skill is applied when you:

• Ask to find orphaned classes in root namespaces
• Request component flattening analysis
• Need to identify component hierarchy issues
• Want to clean up component structure
• Ask about component nesting or hierarchy
• Plan to prepare components for domain grouping
• Discuss component structure cleanup

Key Features

Orphaned Class Detection

Identifies source files in root namespaces:

• Scans root namespaces for source files
• Classifies orphaned classes (shared/domain/mixed)
• Assesses impact and dependencies
• Flags hierarchy violations

Flattening Strategy Analysis

Analyzes multiple flattening options:

1. Consolidate Down: Move leaf code into root namespace 2. Split Up: Move root code into new leaf nodes 3. Extract Shared: Move shared code to .shared component

Component Structure Validation

Ensures components follow rules:

• Components exist only as leaf nodes
• No orphaned classes in root namespaces
• Clear component boundaries
• Proper namespace hierarchy

Files Included

SKILL.md (Main Skill)

The primary skill file containing:

• Component hierarchy detection methodology
• Orphaned class identification process
• Flattening strategy analysis
• Refactoring plan creation
• Output format templates
• Implementation notes for different languages
• Fitness function examples

QUICK-REFERENCE.md (Quick Lookup)

Fast reference for common scenarios:

• Component definition rules
• Orphaned class detection
• Flattening strategies
• Common patterns
• Output template

README.md (This File)

Complete documentation including:

• What the skill does
• When to use it
• Usage examples
• Core concepts
• Integration with other skills

Usage Examples

Example 1: Find Orphaned Classes

User: "Find orphaned classes in root namespaces"

The skill will:
1. Map component namespace structure
2. Identify root namespaces
3. Find source files in root namespaces
4. Classify orphaned classes
5. Create report with recommendations

Output:

## Orphaned Classes Analysis

### Root Namespace: ss.survey

**Orphaned Files** (5 files):

- Survey.js (domain code)
- SurveyProcessor.js (domain code)
- SurveyValidator.js (shared code)

**Issue**: Root namespace contains code but is extended by leaf component

**Recommendation**: Consolidate templates into root namespace

Example 2: Flatten Components

User: "Flatten component hierarchies"

The skill will:
1. Identify all hierarchy issues
2. Analyze flattening options
3. Select best strategy for each
4. Create refactoring plan
5. Estimate effort

Output:

## Flattening Plan

### Priority: High

**ss.survey** → Consolidate Down

- Move 7 files from templates to root
- Effort: 2-3 days
- Risk: Low

**ss.ticket** → Split Up

- Create maintenance, completion, shared components
- Effort: 1 week
- Risk: Medium

Example 3: Component Structure Analysis

User: "Analyze component structure for hierarchy issues"

The skill will:
1. Map namespace hierarchies
2. Identify root namespaces with code
3. Find components built on components
4. Flag violations
5. Provide recommendations

Output:

## Component Hierarchy Issues

| Root Namespace | Orphaned Files | Leaf Components   | Issue                | Recommendation   |
| -------------- | -------------- | ----------------- | -------------------- | ---------------- |
| ss.survey      | 5              | 1 (templates)     | Has orphaned classes | Consolidate down |
| ss.ticket      | 45             | 2 (assign, route) | Large orphaned code  | Split up         |

Core Concepts

Component Definition

A component is identified by a leaf node in directory/namespace structure:

• Leaf Node: Deepest directory containing source files
• Component: Source code files in leaf node namespace
• Subdomain: Parent namespace that has been extended

Key Rule: Components exist only as leaf nodes. If a namespace is extended, the parent becomes a subdomain, not a component.

Root Namespace

A root namespace is a namespace node that has been extended:

• Extended: Another namespace node added below it
• Example: ss.survey extended to ss.survey.templates
• Result: ss.survey becomes a root namespace (subdomain)

Orphaned Classes

Orphaned classes are source files in root namespaces:

• Location: Root namespace (non-leaf node)
• Problem: No definable component associated with them
• Solution: Move to leaf node namespace (component)

Flattening Strategies

Consolidate Down:

• Move code from leaf nodes into root namespace
• Makes root namespace the component
• Use when: Leaf nodes are small, related functionality

Split Up:

• Move code from root namespace into new leaf nodes
• Creates multiple components from root
• Use when: Root namespace has distinct functional areas

Extract Shared:

• Move shared code to .shared component
• Keep domain code in root or split
• Use when: Root namespace has shared utilities

How to Use

Quick Start

Request analysis of your codebase:

"Find orphaned classes in root namespaces"
"Flatten component hierarchies"
"Identify components that need flattening"
"Analyze component structure for hierarchy issues"

Step-by-Step Usage

1. Find Orphaned Classes

Start by identifying hierarchy issues:

User: "Find orphaned classes in root namespaces"

This will:

• Map component structure
• Identify root namespaces
• Find orphaned classes
• Classify and assess impact

2. Analyze Flattening Options

Determine best strategy:

User: "What flattening strategy should I use for ss.survey?"

This will:

• Analyze consolidation option
• Analyze splitting option
• Analyze shared code extraction
• Recommend best approach

3. Create Flattening Plan

Get actionable refactoring plan:

User: "Create a plan to flatten component hierarchies"

This will:

• Select flattening strategies
• Create refactoring steps
• Estimate effort and risk
• Prioritize work

4. Execute Flattening

Perform the refactoring:

User: "Flatten the survey component hierarchy"

This will:

• Move files to target namespaces
• Update imports and references
• Update namespace declarations
• Verify changes

Advanced Usage

Custom Flattening Rules

Specify flattening preferences:

User: "Flatten components, preferring consolidation over splitting"

Specific Namespace Analysis

Focus on specific namespace:

User: "Analyze ss.ticket namespace for flattening"

Shared Code Detection

Identify shared code patterns:

User: "Find shared code that should be extracted to .shared components"

Output Format

The skill generates structured output:

Orphaned Classes Report

## Orphaned Classes Analysis

### Root Namespace: ss.survey

**Status**: ⚠️ Has Orphaned Classes

**Orphaned Files** (5 files):

- Survey.js (domain code)
- SurveyProcessor.js (domain code)
- SurveyValidator.js (shared code)

**Leaf Components**:

- ss.survey.templates (7 files)

**Recommendation**: Consolidate templates into root namespace

Component Hierarchy Issues

## Component Hierarchy Issues

| Root Namespace | Orphaned Files | Leaf Components   | Issue                | Recommendation   |
| -------------- | -------------- | ----------------- | -------------------- | ---------------- |
| ss.survey      | 5              | 1 (templates)     | Has orphaned classes | Consolidate down |
| ss.ticket      | 45             | 2 (assign, route) | Large orphaned code  | Split up         |

Flattening Plan

## Flattening Plan

### Priority: High

**ss.survey** → Consolidate Down

- Move 7 files from templates to root
- Update imports
- Remove templates directory
- Effort: 2-3 days
- Risk: Low

Integration with Other Skills

This skill is part of a decomposition pattern sequence:

1. Component Identification & Sizing → Understand what you have 2. Common Domain Component Detection → Find duplicates 3. Component Flattening (this skill) → Clean structure 4. Component Dependency Analysis → Assess coupling 5. Domain Identification & Grouping → Group into domains 6. Decomposition Planning → Coordinate everything

Use this skill after gathering common components and before dependency analysis.

Installation

This skill is installed at the project level:

skills/component-flattening-analysis/

This means it's:

• Shared with the repository: Anyone cloning this repo gets the skill
• Version controlled: Changes are tracked in git
• Project-specific: Can be customized for this codebase

The skill will be automatically discovered and used when appropriate based on the description in the frontmatter.

Customization

For Project-Specific Patterns

Document your project's component patterns:

skills/component-flattening-analysis/
└── project-patterns.md  # Document project-specific patterns

For Framework-Specific Analysis

Add framework-specific patterns:

## Framework: NestJS

**Component Pattern**: `@Injectable()` classes in modules
**Flattening**: Move nested module classes to parent module
**Shared Code**: Extract to `shared/` directory

Custom Flattening Rules

Modify flattening preferences in SKILL.md:

## Custom Flattening Rules

For this project:

- Always prefer consolidation over splitting
- Extract shared code to `.shared` components
- Maximum 10 files per component before splitting

Fitness Functions

After flattening components, create automated checks:

No Source Code in Root Namespaces

// Alert if source code exists in root namespace
function checkRootNamespaceCode(namespaces, sourceFiles) {
  const violations = []

  namespaces.forEach((ns) => {
    const hasChildren = namespaces.some((n) => n.startsWith(ns + '.') || n.startsWith(ns + '/'))

    if (hasChildren) {
      const files = sourceFiles.filter((f) => f.namespace === ns)
      if (files.length > 0) {
        violations.push({
          namespace: ns,
          files: files.map((f) => f.name),
          issue: 'Root namespace contains source files',
        })
      }
    }
  })

  return violations
}

Components Only as Leaf Nodes

// Ensure components exist only as leaf nodes
function validateComponentStructure(namespaces, sourceFiles) {
  const violations = []

  const leafNodes = namespaces.filter((ns) => {
    return !namespaces.some((n) => n.startsWith(ns + '.') || n.startsWith(ns + '/'))
  })

  sourceFiles.forEach((file) => {
    if (!leafNodes.includes(file.namespace)) {
      violations.push({
        file: file.name,
        namespace: file.namespace,
        issue: 'Source file not in leaf node',
      })
    }
  })

  return violations
}

Best Practices

Do's ✅

• Ensure components exist only as leaf nodes
• Remove orphaned classes from root namespaces
• Choose flattening strategy based on functionality
• Consolidate when functionality is related
• Split when functionality is distinct
• Extract shared code to .shared components
• Update all references after flattening
• Verify changes with tests

Don'ts ❌

• Don't leave orphaned classes in root namespaces
• Don't create components on top of other components
• Don't skip updating imports after moving files
• Don't flatten without analyzing impact
• Don't mix flattening strategies inconsistently
• Don't ignore shared code when flattening
• Don't skip testing after refactoring

Common Patterns

Pattern 1: Simple Consolidation

Before:

ss.survey/
├── Survey.js           ← Orphaned
└── templates/          ← Component
    └── Template.js

After:

ss.survey/              ← Component (leaf node)
├── Survey.js
└── Template.js

Pattern 2: Functional Split

Before:

ss.ticket/              ← Root namespace
├── Ticket.js           ← Orphaned (45 files)
├── assign/             ← Component
└── route/              ← Component

After:

ss.ticket/              ← Subdomain
├── maintenance/        ← Component
├── completion/         ← Component
├── assign/             ← Component
└── route/              ← Component

Pattern 3: Shared Code Extraction

Before:

ss.survey/              ← Root namespace
├── Survey.js           ← Domain code
├── SurveyValidator.js  ← Shared code
└── templates/          ← Component

After:

ss.survey/              ← Component
├── Survey.js
└── shared/             ← Component
    └── SurveyValidator.js

Troubleshooting

Too Many Orphaned Classes

Issue: Found many orphaned classes

Solution:

• Prioritize by impact
• Start with high-priority namespaces
• Flatten incrementally
• Consider splitting large root namespaces

Unclear Flattening Strategy

Issue: Not sure which strategy to use

Solution:

• Analyze functionality similarity
• Consider component size
• Assess coupling impact
• Choose simplest approach that works

Breaking References

Issue: Moving files breaks imports

Solution:

• Update all imports before moving
• Use IDE refactoring tools
• Run tests after each move
• Update namespace declarations

References

This skill is based on:

• Software Architecture: The Hard Parts by Neal Ford, Mark Richards, Pramod Sadalage, Zhamak Dehghani
• Flatten Components Pattern (Chapter 5)
• Fundamentals of Software Architecture by Mark Richards & Neal Ford

Contributing

To improve this skill:

1. Add language-specific flattening patterns 2. Expand framework-specific component detection 3. Add more flattening strategy examples 4. Document new anti-patterns or red flags 5. Share real-world case studies

Version

Version: 1.0.0 Created: 2026-02-05 Based on: Flatten Components Pattern from "Software Architecture: The Hard Parts"

---

Quick Start

To use this skill immediately:

User: "Find orphaned classes in root namespaces"
User: "Flatten component hierarchies"
User: "Identify components that need flattening"
User: "Analyze component structure for hierarchy issues"

This skill will automatically be applied to provide comprehensive component flattening analysis and recommendations.