Refactoring Design Map: python3-development

Refactoring Design Map: python3-development

Overview

The python3-development plugin requires significant refactoring to address a 1,318-line monolithic SKILL.md covering 5+ distinct domains, non-standard command frontmatter, and orphaned planning documentation. This design splits the monolithic skill into 5 focused skills under 400 lines each, standardizes command schemas, and resolves structural issues while preserving all existing functionality.

Source Assessment

• Plugin: ./plugins/python3-development
• Overall Score: 62/100 (from Phase 1 assessment)
• Total Refactoring Targets: 12
  • 1 skill split (into 5 new skills)
  • 6 command frontmatter fixes
  • 1 orphan resolution
  • 4 documentation improvements

Skill Splits

python3-development Split Plan

Source: ./plugins/python3-development/skills/python3-development/SKILL.md Lines: 1,318 Domains Identified:

1. Orchestration and Workflow (~200 lines) - Agent delegation, pre-delegation protocol, workflow patterns
2. Type Safety (~300 lines) - Generics, Protocols, TypedDict, type narrowing, mypy configuration
3. CLI Development (~200 lines) - Typer/Rich patterns, Rich width handling, emoji usage, exception handling
4. Quality and Linting (~250 lines) - Linting discovery, format-first workflow, type checker discovery, quality gates
5. Project Standards (~200 lines) - Project structure, script trade-offs, PEP 723, asset templates, command usage

Proposed Split:

Skill 1: python3-workflow

Purpose: Agent orchestration and development workflow patterns for Python projects

Frontmatter:

---
name: python3-workflow
description: 'Use when: 1. Delegating Python development tasks to agents. 2. Planning TDD, feature addition, or refactoring workflows. 3. Coordinating multi-agent Python implementations. 4. Reviewing orchestration guide requirements. Provides: Agent selection criteria, pre-delegation checklists, workflow patterns (TDD/feature/refactor/debug/review), quality gate sequencing.'
---

Content Structure:

# Python Development Workflow Orchestration

## Role Identification (Mandatory)
[Keep existing role identification section - lines 11-35]

<section ROLE_TYPE="orchestrator">

## Agent Orchestration (Orchestrator Only)

### STOP - MANDATORY PRE-DELEGATION PROTOCOL
[Lines 719-731 - Pre-delegation checklist]

### Why This Protocol Exists
[Lines 733-740]

### DO NOT Pre-Gather Data for Agents
[Lines 754-776]

### Delegation Pattern
[Lines 778-805 - Delegation table]

### Required Reading (MANDATORY)
[Lines 806-819]

### Quick Reference Example
[Lines 820-846]

## Core Workflows (Orchestrator Only)
[Lines 924-940]

## Common Patterns to Follow (Orchestrator Only)
[Lines 1227-1246]

</section>

## Summary for All Roles
[Brief summary with link to orchestration guide reference]

Shared References:

• ./references/python-development-orchestration.md (primary reference)
• ./references/accessing_online_resources.md (symlink)

Migration Notes:

• This skill focuses ONLY on orchestration patterns
• Sub-agents do NOT need this skill - they receive task instructions directly
• Must include ROLE_TYPE sections to maintain orchestrator-only guidance

Skill 2: python3-typing

Purpose: Comprehensive type annotation patterns for Python 3.11+

Frontmatter:

---
name: python3-typing
description: 'Use when: 1. Adding type hints to Python code. 2. Working with Generics, Protocols, or TypedDict. 3. Configuring mypy or fixing type errors. 4. Using type narrowing or TypeGuard patterns. 5. Choosing between attrs, dataclasses, and pydantic. Provides: Python 3.11+ native type hints, Generic patterns, Protocol structural typing, TypedDict schemas, type narrowing, mypy configuration.'
---

Content Structure:

# Python Type Safety with Mypy

## Type Safety Requirements
[Brief intro - requirement for comprehensive typing]

## When to Use Generics
[Lines 281-351 - Generic patterns with TypeVar]

## When to Use Protocols
[Lines 365-436 - Protocol patterns for structural typing]

## TypedDict for Dictionary Typing
[Lines 438-506 - TypedDict patterns]

## Type Narrowing
[Lines 508-569 - isinstance, None checks, TypeGuard, TypeIs]

## attrs vs dataclasses vs pydantic
[Lines 571-639 - Decision matrix and patterns]

## Additional Mypy Features
[Lines 641-677 - Generic dataclasses, Self type]

## Mypy Configuration Best Practices
[Lines 679-711 - pyproject.toml configuration]

Shared References:

• ./references/mypy-docs/generics.rst
• ./references/mypy-docs/protocols.rst
• ./references/mypy-docs/typed_dict.rst
• ./references/mypy-docs/type_narrowing.rst
• ./references/mypy-docs/additional_features.rst
• ./references/tool-library-registry.md (for mypy config section)

Migration Notes:

• Largest skill due to comprehensive type patterns
• All mypy-docs references remain unchanged
• No ROLE_TYPE sections needed - applies to all roles

Skill 3: python3-cli

Purpose: CLI development patterns with Typer and Rich

Frontmatter:

---
name: python3-cli
description: 'Use when: 1. Building CLI applications with Typer or Rich. 2. Fixing Rich Panel/Table width wrapping issues. 3. Handling exceptions in CLI apps. 4. Using Rich emoji tokens. 5. Creating CLI output for CI/non-TTY environments. Provides: Typer+Rich integration patterns, width handling solutions, exception handling patterns, Rich emoji usage, CI-compatible output.'
---

Content Structure:

# Python CLI Development with Typer and Rich

## Script Dependency Trade-offs
[Lines 127-156 - When to use Typer+Rich vs stdlib]

## Rich Panel and Table Width Handling
[Lines 157-217 - get_rendered_width() pattern]

## Rich Emoji Usage
[Lines 219-247 - Token patterns]

## Python Exception Handling
[Lines 249-271 - Fail-fast principle]

## Exception Handling in CLI Applications
[Brief section pointing to reference]

Shared References:

• ./references/exception-handling.md (critical for Typer exception chain prevention)
• ./assets/typer_examples/index.md
• ./assets/typer_examples/console_no_wrap_example.py
• ./assets/typer_examples/console_containers_no_wrap.py

Migration Notes:

• Keep executable examples in assets/
• Exception handling reference is critical for Typer apps
• No ROLE_TYPE sections needed - applies to all roles

Skill 4: python3-quality

Purpose: Linting, formatting, and quality gate execution

Frontmatter:

---
name: python3-quality
description: 'Use when: 1. Running linting or formatting on Python code. 2. Discovering project linters (pre-commit, prek, ruff, mypy). 3. Resolving linting errors at root cause. 4. Setting up quality gates. 5. Working with basedpyright, pyright, or mypy type checkers. Provides: Linting discovery protocol, format-first workflow, type checker detection, quality gate sequences, linting exception conditions.'
---

Content Structure:

# Python Code Quality and Linting

## Linting Discovery Protocol
[Lines 944-1046 - Discovery sequence, format-first, type checker discovery]

## Quality Gates
[Lines 1047-1079 - Gate sequence with type checker detection]

## Linting Exception Conditions
[Lines 1087-1129 - When to ignore vs fix]

Shared References:

• ./references/tool-library-registry.md (for tool configurations)
• ./references/user-project-conventions.md (for ruff/mypy settings)

Migration Notes:

• Critical integration with holistic-linting skill
• Must detect both pre-commit and prek tools
• Include CI compatibility verification

Skill 5: python3-project

Purpose: Project structure, standards, and configuration

Frontmatter:

---
name: python3-project
description: 'Use when: 1. Creating new Python projects or packages. 2. Setting up pyproject.toml configuration. 3. Using PEP 723 inline script metadata. 4. Copying asset templates (version.py, pre-commit config). 5. Understanding standard project structure. Provides: Project layout standards, pyproject.toml templates, PEP 723 guidance, asset template usage, command usage (/modernpython, /shebangpython).'
---

Content Structure:

# Python Project Standards

## Python Development Standards
[Lines 98-126 - Core concepts, docstring standard, template variables]

## Standard Project Structure
[Lines 1130-1162 - Directory layout, hatchling config]

## Using Asset Templates
[Lines 1182-1226 - Template usage instructions]

## Command Usage
[Lines 848-923 - /modernpython and /shebangpython]

## Integration
[Lines 1163-1181 - External reference example]

## Detailed Documentation
[Lines 1248-1292 - Reference links]

Shared References:

• ./references/PEP723.md
• ./references/user-project-conventions.md
• ./references/tool-library-registry.md (template variable reference)
• ./references/modern-modules.md
• ./assets/ directory (all templates)

Migration Notes:

• Keep all asset templates in existing location
• Commands reference external files in ~/.claude/commands/
• Include reference navigation helpers (grep commands)

Shared Reference Strategy

All 5 new skills share access to the existing references/ directory:

Directory Structure After Split:

plugins/python3-development/
├── skills/
│   ├── python3-workflow/
│   │   └── SKILL.md
│   ├── python3-typing/
│   │   └── SKILL.md
│   ├── python3-cli/
│   │   └── SKILL.md
│   ├── python3-quality/
│   │   └── SKILL.md
│   └── python3-project/
│       ├── SKILL.md
│       ├── references/           # Moved from python3-development
│       │   ├── python-development-orchestration.md
│       │   ├── exception-handling.md
│       │   ├── PEP723.md
│       │   ├── user-project-conventions.md
│       │   ├── tool-library-registry.md
│       │   ├── modern-modules.md
│       │   ├── modern-modules/
│       │   ├── mypy-docs/
│       │   ├── api_reference.md
│       │   └── accessing_online_resources.md -> symlink
│       └── assets/               # Moved from python3-development
│           ├── typer_examples/
│           ├── version.py
│           ├── hatch_build.py
│           └── ...
├── commands/
│   ├── development/
│   └── testing/
├── plugin.json
└── README.md

Rationale for References Location:

• References stay with python3-project as the primary skill
• Other skills reference files using relative paths: ../python3-project/references/
• Alternative: Create shared references/ at plugin level and update all paths

Command Frontmatter Fixes

Current Schema Issues

All 6 commands use non-standard frontmatter:

Commands to Fix

1. create-feature-task.md

Source: ./plugins/python3-development/commands/development/create-feature-task.md

Current Frontmatter:

---
title: "Create Feature Development Task"
description: "Set up comprehensive feature development task with proper tracking"
command_type: "development"
last_updated: "2025-11-02"
related_docs:
  - "./use-command-template.md"
  - "../../references/python-development-orchestration.md"
---

Target Frontmatter:

---
name: create-feature-task
description: 'Create structured feature development task with tracking. Use when: starting new feature work, setting up task phases, creating development checkpoints.'
argument-hint: "[feature-name]"
---

Changes:

• Remove title (use name or let it default from filename)
• Remove command_type (not in schema)
• Remove last_updated (not in schema)
• Remove related_docs (put in content as markdown links)
• Add argument-hint for better autocomplete
• Rewrite description with trigger keywords

2. use-command-template.md

Source: ./plugins/python3-development/commands/development/use-command-template.md

Target Frontmatter:

---
name: use-command-template
description: 'Create new slash command from template. Use when: adding custom commands, creating development shortcuts, setting up workflow automation.'
argument-hint: "[command-name]"
---

3. command-template.md (template file)

Source: ./plugins/python3-development/commands/development/templates/command-template.md

Target Frontmatter:

---
name: command-template
description: 'Template for creating new slash commands. Not for direct invocation - copy and customize for new commands.'
user-invocable: false
---

Changes:

• Add user-invocable: false since it's a template, not a command

4. analyze-test-failures.md

Source: ./plugins/python3-development/commands/testing/analyze-test-failures.md

Target Frontmatter:

---
name: analyze-test-failures
description: 'Analyze failing tests with investigative approach. Use when: tests fail unexpectedly, determining if test or implementation is wrong, debugging test assertions.'
argument-hint: "[test-file-or-function]"
---

5. comprehensive-test-review.md

Source: ./plugins/python3-development/commands/testing/comprehensive-test-review.md

Target Frontmatter:

---
name: comprehensive-test-review
description: 'Review test suite for completeness and quality. Use when: auditing test coverage, reviewing test patterns, assessing test suite health.'
argument-hint: "[test-directory]"
---

6. test-failure-mindset.md

Source: ./plugins/python3-development/commands/testing/test-failure-mindset.md

Target Frontmatter:

---
name: test-failure-mindset
description: 'Load test debugging mindset guidelines. Use when: approaching test failures, avoiding assumption that tests are wrong, systematic failure analysis.'
---

Orphan Resolution

planning/reference-document-architecture.md

Source: ./plugins/python3-development/skills/python3-development/planning/reference-document-architecture.md

Classification: Historical Proposal (Working Notes)

Current Status:

• Not linked from SKILL.md or any reference file
• Frontmatter explicitly states: status: "historical-proposal", implementation_status: "not-implemented"
• Contains architectural proposal that was never implemented

Resolution: Archive or Remove

Recommendation: Move to documentation or remove entirely

Option A - Archive (Recommended):

1. Move to ./plugins/python3-development/docs/archive/reference-document-architecture.md
2. Add link from README.md under "Historical Documentation" section

Option B - Remove:

1. Delete the file since it's marked as not-implemented
2. The actual skill structure differs significantly from this proposal

Implementation:

# Option A - Archive
mkdir -p ./plugins/python3-development/docs/archive/
mv ./plugins/python3-development/skills/python3-development/planning/reference-document-architecture.md \
   ./plugins/python3-development/docs/archive/
rmdir ./plugins/python3-development/skills/python3-development/planning/

# Update README.md to mention archived docs

Documentation Improvements

1. plugin.json Description

Target: ./plugins/python3-development/plugin.json

Current Issue: File does not exist (404 error in assessment read)

Action: Create plugin.json with proper metadata

Target Content:

{
  "name": "python3-development",
  "version": "2.0.0",
  "description": "Python 3.11+ development patterns, type safety, CLI tools, and quality workflows",
  "author": "User",
  "license": "MIT",
  "keywords": ["python", "typing", "typer", "rich", "mypy", "ruff", "pytest"],
  "skills": [
    "python3-workflow",
    "python3-typing",
    "python3-cli",
    "python3-quality",
    "python3-project"
  ],
  "commands": {
    "development": ["create-feature-task", "use-command-template"],
    "testing": ["analyze-test-failures", "comprehensive-test-review", "test-failure-mindset"]
  }
}

2. Reference Files Back-Links

Target: All 26 reference files in ./references/

Current Issue: No navigation headers pointing back to parent skill

Action: Add navigation header to each reference file

Template:

---
[existing frontmatter]
parent_skill: python3-project
---

> **Navigation**: [Back to Python Project Standards](../SKILL.md) | [Reference Index](./modern-modules.md)

[existing content]

Priority: Low - Can be done incrementally

3. Skill Description Optimization

All 5 new skills need trigger-optimized descriptions (already specified in Skill Splits section above).

Verification Checklist:

• Under 1024 characters
• Contains "Use when:" trigger phrases
• Contains "Provides:" capability list
• No YAML multiline indicators
• Single-quoted if contains special characters

Dependency Map

                    ┌─────────────────────────────────────────────────────┐
                    │                  PHASE 1: STRUCTURE                  │
                    │   (Create directories, plugin.json, archive orphan)  │
                    └─────────────────────────────────────────────────────┘
                                             │
                                             ▼
         ┌───────────────────────────────────┴───────────────────────────────────┐
         │                                                                       │
         ▼                                                                       ▼
┌─────────────────────────┐                                       ┌─────────────────────────┐
│   PHASE 2A: SKILL SPLIT │                                       │  PHASE 2B: CMD FIXES    │
│   (5 new SKILL.md files)│                                       │  (6 frontmatter fixes)  │
└─────────────────────────┘                                       └─────────────────────────┘
         │                                                                       │
         │  ┌─────────────┬─────────────┬─────────────┬─────────────┐           │
         │  │             │             │             │             │           │
         ▼  ▼             ▼             ▼             ▼             ▼           │
    python3-      python3-      python3-      python3-      python3-            │
    workflow      typing        cli           quality       project             │
         │             │             │             │             │              │
         └─────────────┴─────────────┴─────────────┴─────────────┴──────────────┘
                                             │
                                             ▼
                    ┌─────────────────────────────────────────────────────┐
                    │                  PHASE 3: REFERENCES                 │
                    │      (Move references to python3-project, update     │
                    │       relative paths in other skills)                │
                    └─────────────────────────────────────────────────────┘
                                             │
                                             ▼
                    ┌─────────────────────────────────────────────────────┐
                    │                  PHASE 4: VALIDATION                 │
                    │      (Test skill loading, verify cross-references,   │
                    │       run pre-commit, update README)                 │
                    └─────────────────────────────────────────────────────┘

Parallelization Opportunities

Phase 2A: Skill Split (Parallelizable)

All 5 skills can be created simultaneously as they have no dependencies on each other during creation:

Group A - No dependencies between tasks:

Phase 2B: Command Fixes (Parallelizable)

All 6 commands can be fixed simultaneously:

Group B - No dependencies between tasks:

Sequential Dependencies

• Phase 1 MUST complete before Phase 2 (directory structure required)
• Phase 2 MUST complete before Phase 3 (skills must exist before moving references)
• Phase 3 MUST complete before Phase 4 (paths must be correct before validation)

Implementation Task List

Phase 1: Structure Setup

Phase 2A: Skill Split

Phase 2B: Command Fixes

Phase 3: Reference Migration

Phase 4: Validation

Risk Assessment

Success Criteria

Quantitative

• Each new skill is under 400 lines (target: 200-350)
• All 5 new skills load without errors
• All 6 commands appear in /help menu with descriptions
• All reference file links resolve correctly
• Pre-commit passes on all modified files
• No content lost from original SKILL.md

Qualitative

• Each skill has single, focused domain
• Skill descriptions contain clear trigger keywords
• Progressive disclosure pattern maintained (SKILL.md -> references/)
• Orchestrator-only sections preserved in python3-workflow
• Asset templates remain accessible from python3-project

Rollback Plan

If issues discovered after migration:

1. Restore from git: All changes tracked in git, can revert to pre-refactor state
2. Keep old skill temporarily: Rename to python3-development-legacy/ during transition
3. Symlink fallback: Update ~/.claude/skills/ symlink to point to legacy skill

Document Metadata

• Created: 2026-01-22
• Author: python-cli-design-spec agent
• Assessment Source: Plugin assessment report (Phase 1)
• Target Plugin: ./plugins/python3-development
• Target Score: 85+/100 (from 62/100)