markitect-main/.markitect_workspace/issue_38/GAMEPLAN.md

GAMEPLAN for Issue #38: Content Commands - Access Content Stats and Raw Content Separately

🎯 OBJECTIVE (Updated Scope)

Implement dedicated CLI commands for content analysis and raw content access, completing the foundation of granular markdown component access. This issue now focuses specifically on content commands after decomposing the original broader scope into separate issues:

• Issue #41: Frontmatter Commands
• Issue #42: Contentmatter Commands
• Issue #43: Tailmatter Commands

📋 REQUIREMENTS ANALYSIS

Current State Assessment:

• ✅ markitect metadata command renamed to db-data (Phase 1 completed)
• ✅ Backward compatibility maintained with deprecation warnings
• 🎯 Current Focus: Implement content analysis and raw content access commands

Target Architecture (Content Commands Only):

Based on MarkdownMatters.md specification, this issue focuses on:

1. Content Statistics: Word count, line count, heading analysis, link analysis
2. Raw Content Access: Extract clean markdown content without frontmatter/tailmatter
3. Content Processing: Strip matter blocks, analyze structure, provide metrics

🚀 IMPLEMENTATION PHASES

Phase 1: Command Restructuring (Foundation) ✅ COMPLETED

• Rename metadata command to db-data
• Update all references in codebase and tests
• Maintain backward compatibility with deprecation warnings
• Update CLI help and documentation

Phase 2: Content Commands (Current Focus)

• Create content_processor.py module with ContentStats and ContentProcessor classes
• Implement content-stats command - Statistics about content (word count, line count, headings, etc.)
• Implement content-get [path] command - Echo content without frontmatter and tailmatter
• Comprehensive testing for both commands
• Integration with existing CLI patterns

Related Issues (Now Separate)

The following phases have been moved to separate issues for focused development:

• Phase 3: Frontmatter Commands → Issue #41: Frontmatter Commands - YAML/JSON Header Manipulation
• Phase 4: Contentmatter Commands → Issue #42: Contentmatter Commands - MMD Key-Value Processing
• Phase 5: Tailmatter Commands → Issue #43: Tailmatter Commands - QA and Editorial Metadata Management

🧪 TESTING STRATEGY

Test Organization (Updated for Content Commands Focus):

• ✅ test_issue_38_command_restructuring.py - Phase 1 tests (completed)
• 🎯 test_issue_38_content_commands.py - Phase 2 content commands tests (current focus)

Test Categories:

1. Command Existence Tests - Verify all commands are properly registered
2. Functionality Tests - Test core behavior for each command
3. Error Handling Tests - Invalid files, missing keys, malformed content
4. Format Support Tests - JSON, YAML, table output formats
5. Integration Tests - Commands working together in workflows
6. Performance Tests - Large file handling and response times

🏗️ TECHNICAL ARCHITECTURE

New Module Structure (Content Commands Focus):

markitect/
├── content_processor.py      # Content parsing and analysis (THIS ISSUE)
└── [Other processors moved to separate issues]

Data Models (Content Commands Focus):

@dataclass
class ContentStats:
    word_count: int
    line_count: int
    character_count: int
    heading_counts: Dict[int, int]  # level -> count
    link_count: int
    external_link_count: int
    image_count: int
    code_block_count: int
    list_item_count: int

class ContentProcessor:
    def analyze_content(self, content: str) -> ContentStats
    def extract_content(self, markdown: str) -> str
    def strip_frontmatter(self, content: str) -> str
    def strip_tailmatter(self, content: str) -> str

CLI Commands (This Issue):

• content-stats - Comprehensive content analysis and statistics
• content-get - Extract raw content without frontmatter/tailmatter
• ✅ db-data - Complete data access (renamed from metadata, completed)

📊 SUCCESS METRICS

Functional Success (Updated for Content Commands):

• 2 new content CLI commands implemented and working
• Complete test coverage (>95%) for content command functionality
• Backward compatibility maintained for existing workflows
• Performance within 10% of current db-data command speed

User Experience Success:

• Intuitive command naming following consistent patterns
• Comprehensive help documentation for all commands
• Consistent output formatting across all commands
• Clear error messages for all failure scenarios

Technical Success (Content Commands Focus):

• Clean content processing module with clear responsibilities
• Extensible ContentProcessor architecture for future content analysis features
• Efficient markdown parsing and content extraction
• Thread-safe operation for concurrent content analysis

⚡ IMPLEMENTATION APPROACH

TDD8 Methodology:

1. ISSUE: Break down into manageable sub-issues for each phase
2. TEST: Write comprehensive tests for each command before implementation
3. RED: Ensure tests fail initially (proper TDD red state)
4. GREEN: Implement minimal code to make tests pass
5. REFACTOR: Clean up implementation and optimize performance
6. DOCUMENT: Update CLI help, README, and user documentation
7. REFINE: Performance testing and edge case handling
8. PUBLISH: Integration testing and final validation

Development Order (Updated for Content Commands Focus):

1. ✅ Complete Phase 1 (command restructuring) - DONE
2. 🎯 Implement Phase 2 (content commands) - CURRENT FOCUS
   • Create content_processor.py module
   • Implement content-stats command
   • Implement content-get command
   • Comprehensive testing

🎯 IMMEDIATE NEXT STEPS

1. ✅ Phase 1 Tests and Implementation - COMPLETED
2. ✅ Implement db-data Command - COMPLETED
3. 🎯 Create Content Processor Module: Foundation for content analysis (NEXT)
4. 🎯 Implement content-stats Command: Content analysis and statistics (NEXT)
5. 🎯 Implement content-get Command: Raw content extraction (NEXT)

📝 NOTES

• Backward Compatibility: Maintain metadata command with deprecation warning
• Performance: Cache parsed components to avoid re-parsing for related commands
• Error Handling: Graceful degradation for malformed markdown files
• Output Formats: Support table, JSON, YAML formats consistently across all commands
• Documentation: Reference MarkdownMatters.md specification for implementation details

---

Estimated Timeline: 3-5 days for content commands implementation Risk Level: Low (focused scope, clear requirements, foundation completed) Dependencies: Existing CLI infrastructure, markdown parsing capabilities

🔗 RELATED ISSUES

• Issue #41: Frontmatter Commands - YAML/JSON Header Manipulation
• Issue #42: Contentmatter Commands - MMD Key-Value Processing
• Issue #43: Tailmatter Commands - QA and Editorial Metadata Management
• Issue #39: Database Command Reorganization (foundation completed)