Analytical-Guide · Copilot · Nov 13, 2025 · Nov 13, 2025 · Nov 13, 2025 · Nov 13, 2025
diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md
@@ -0,0 +1,34 @@
+---
+name: Codebase Cleanup Task
+about: Template for codebase cleanup issues
+title: '[CLEANUP] '
+labels: cleanup
+assignees: ''
+
+---
+
+## Problem Description
+<!-- Describe the current state and what needs to be cleaned up -->
+
+## Current State Analysis
+<!-- Detail the current situation with specific file references -->
+
+## Impact
+<!-- Explain why this matters and what problems it causes -->
+
+## Recommended Solution
+<!-- Provide specific, actionable recommendations -->
+
+## Files to Check/Update
+<!-- List all files that need attention -->
+- [ ] File 1
+- [ ] File 2
+
+## Definition of Done
+<!-- Clear checklist of what "complete" looks like -->
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Related Issues
+<!-- Link to other related issues -->
+
diff --git a/CLEANUP_SUMMARY.md b/CLEANUP_SUMMARY.md
@@ -0,0 +1,167 @@
+# Codebase Cleanup - Issues Summary
+
+## Overview
+
+This directory contains documentation for a comprehensive cleanup of the Product Analytics MasterClass repository. Seven detailed GitHub issues have been prepared to systematically address organizational and structural problems in the codebase.
+
+## Files in This Package
+
+1. **ISSUES_TO_CREATE.md** (Main document - ~500 lines)
+   - Contains 7 fully detailed GitHub issues
+   - Each issue includes problem description, analysis, solutions, and definition of done
+   - Ready to be copied to GitHub Issues one at a time
+
+2. **HOW_TO_CREATE_ISSUES.md** (Instructions)
+   - Step-by-step guide for creating issues on GitHub
+   - Includes manual method, CLI method, and automated script
+   - Provides checklist and best practices
+
+3. **.github/ISSUE_TEMPLATE.md** (Template)
+   - Reusable template for future cleanup issues
+   - Ensures consistency in issue creation
+
+## The 7 Issues
+
+### Issue #1: Consolidate duplicate build_book.sh scripts
+- **Priority:** High
+- **Effort:** Small (1-2 hours)
+- **Labels:** `cleanup`, `documentation`, `scripts`
+- **Summary:** Remove duplicate build scripts and standardize on one
+
+### Issue #2: Evaluate Content folder usage and redundancy
+- **Priority:** Medium
+- **Effort:** Medium (3-4 hours)
+- **Labels:** `cleanup`, `documentation`, `content-structure`
+- **Summary:** Determine purpose of Content/ folder and eliminate redundancy
+
+### Issue #3: Restore or remove week directory structure in book-src
+- **Priority:** High
+- **Effort:** Small-Medium (2-3 hours)
+- **Labels:** `cleanup`, `structure`, `decision-needed`
+- **Summary:** Decide whether to restore week-based organization or keep flat structure
+
+### Issue #4: Populate or remove empty placeholder report files
+- **Priority:** Medium
+- **Effort:** Large (8-12 hours if creating content)
+- **Labels:** `cleanup`, `content`, `reports`
+- **Summary:** Fill in or remove 9 empty/placeholder report files
+
+### Issue #5: Review and update documentation files for consistency
+- **Priority:** Medium
+- **Effort:** Medium (3-4 hours)
+- **Labels:** `documentation`, `cleanup`, `consistency`
+- **Summary:** Update README, CONTRIBUTING, and other docs to reflect current structure
+
+### Issue #6: Improve SUMMARY.md generation and book navigation
+- **Priority:** High
+- **Effort:** Small-Medium (2-3 hours)
+- **Labels:** `enhancement`, `user-experience`, `mdbook`
+- **Summary:** Enhance mdBook table of contents for better navigation
+
+### Issue #7: Comprehensive codebase audit and cleanup roadmap
+- **Priority:** High
+- **Effort:** Medium (4-6 hours for audit)
+- **Labels:** `epic`, `cleanup`, `planning`
+- **Summary:** Meta-issue to track overall cleanup progress and identify additional items
+
+## Recommended Creation Order
+
+1. **Issue #1** - Quick win that unblocks other work
+2. **Issue #2** - Strategic decision about content organization
+3. **Issue #3** - Depends on Issue #2 decision
+4. **Issue #4** - Can be done in parallel with others
+5. **Issue #5** - Should be done after #1-3 are resolved
+6. **Issue #6** - Depends on decisions from #2 and #3
+7. **Issue #7** - Meta-issue to track everything
+
+## Quick Start
+
+### Option 1: Manual Creation (5-10 minutes per issue)
+1. Open `ISSUES_TO_CREATE.md`
+2. Copy each issue section
+3. Create new GitHub issue
+4. Paste content and add labels
+5. Repeat for all 7 issues
+
+### Option 2: Automated Creation (5 minutes total)
+1. Read `HOW_TO_CREATE_ISSUES.md`
+2. Use the provided bash script
+3. Run: `./create_issues.sh`
+4. All 7 issues created automatically
+
+## What's Included in Each Issue
+
+Every issue contains:
+
+- ✅ **Problem Description** - Clear explanation of what needs fixing
+- ✅ **Current State Analysis** - Detailed assessment with file references
+- ✅ **Impact** - Why this matters and what problems it causes
+- ✅ **Recommended Solutions** - Multiple options with pros/cons
+- ✅ **Files to Check/Update** - Specific file checklist
+- ✅ **Definition of Done** - Clear completion criteria
+- ✅ **Related Issues** - Cross-references to other issues
+- ✅ **Additional Context** - Background information and rationale
+
+## Total Effort Estimate
+
+- **Audit & Planning:** 6-10 hours (Issues #7, #2, #3)
+- **Quick Wins:** 3-5 hours (Issues #1, #6)
+- **Documentation:** 3-4 hours (Issue #5)
+- **Content Creation:** 8-12 hours (Issue #4, if creating content)
+
+**Total:** 20-31 hours depending on decisions made
+
+## Dependencies Between Issues
+
+```
+Issue #1 (Build scripts)
+  └─> Issue #5 (Documentation) - docs reference build scripts
+
+Issue #2 (Content folder)
+  └─> Issue #3 (Week directories) - structure decision
+  └─> Issue #6 (SUMMARY.md) - navigation depends on structure
+
+Issue #3 (Week directories)
+  └─> Issue #6 (SUMMARY.md) - navigation depends on structure
+
+Issue #4 (Reports)
+  └─> Issue #6 (SUMMARY.md) - what to list in TOC
+
+Issue #7 (Audit)
+  └─> All issues - tracks overall progress
+```
+
+## Success Criteria
+
+This cleanup effort will be successful when:
+
+1. ✅ No duplicate or conflicting files exist
+2. ✅ All documentation is current and accurate
+3. ✅ Build process is streamlined and well-documented
+4. ✅ Content organization is clear and logical
+5. ✅ All files have a clear purpose and are referenced
+6. ✅ Navigation experience is smooth for learners
+7. ✅ Repository is easy to maintain going forward
+
+## Getting Help
+
+- Read the full issue descriptions in `ISSUES_TO_CREATE.md`
+- Follow the creation guide in `HOW_TO_CREATE_ISSUES.md`
+- Use `.github/ISSUE_TEMPLATE.md` for any new cleanup issues
+- Reference this summary for overview and priorities
+
+## Next Steps
+
+1. Review `ISSUES_TO_CREATE.md` to understand all issues
+2. Follow `HOW_TO_CREATE_ISSUES.md` to create issues on GitHub
+3. Prioritize and assign issues to team members
+4. Begin work on Issue #1 (quick win)
+5. Make strategic decisions on Issues #2 and #3
+6. Track progress using Issue #7 as epic
+
+---
+
+**Created:** 2025-11-13  
+**Repository:** Analytical-Guide/Product-Analytics-MasterClass  
+**Purpose:** Comprehensive codebase cleanup and organization
+
diff --git a/HOW_TO_CREATE_ISSUES.md b/HOW_TO_CREATE_ISSUES.md
@@ -0,0 +1,157 @@
+# How to Create GitHub Issues from ISSUES_TO_CREATE.md
+
+This guide explains how to create the cleanup issues one at a time on GitHub.
+
+## Prerequisites
+
+- GitHub account with write access to the repository
+- Familiarity with GitHub Issues interface
+
+## Method 1: Using GitHub Web UI (Recommended)
+
+For each issue in `ISSUES_TO_CREATE.md`:
+
+1. **Navigate to Issues**
+   - Go to https://github.com/Analytical-Guide/Product-Analytics-MasterClass/issues
+   - Click "New Issue" button
+
+2. **Copy Issue Content**
+   - Open `ISSUES_TO_CREATE.md` in the repository
+   - Find the issue section (e.g., "## Issue #1: ...")
+   - Copy everything from the title to the end of that issue's content
+   - Stop before the next "## Issue #X" heading
+
+3. **Create the Issue**
+   - Paste the copied content into the issue description
+   - Extract the title from the first line (e.g., "Consolidate duplicate build_book.sh scripts")
+   - Add appropriate labels as specified in the issue
+   - Submit the issue
+
+4. **Repeat for Each Issue**
+   - Follow the recommended order:
+     1. Issue #1 (Build scripts)
+     2. Issue #2 (Content folder)
+     3. Issue #3 (Week directories)
+     4. Issue #4 (Report files)
+     5. Issue #5 (Documentation)
+     6. Issue #6 (SUMMARY.md)
+     7. Issue #7 (Audit roadmap)
+
+## Method 2: Using GitHub CLI
+
+If you have `gh` CLI installed and authenticated:
+
+```bash
+# Navigate to repository
+cd /path/to/Product-Analytics-MasterClass
+
+# Create Issue #1
+gh issue create \
+  --title "Consolidate duplicate build_book.sh scripts" \
+  --label "cleanup,documentation,scripts" \
+  --body-file <(sed -n '/^## Issue #1/,/^## Issue #2/p' ISSUES_TO_CREATE.md | head -n -1)
+
+# Create Issue #2
+gh issue create \
+  --title "Evaluate Content folder usage and redundancy" \
+  --label "cleanup,documentation,content-structure" \
+  --body-file <(sed -n '/^## Issue #2/,/^## Issue #3/p' ISSUES_TO_CREATE.md | head -n -1)
+
+# ... repeat for issues #3-7
+```
+
+## Method 3: Automated Script
+
+A bash script to create all issues at once:
+
+```bash
+#!/bin/bash
+
+# Array of issue titles
+titles=(
+  "Consolidate duplicate build_book.sh scripts"
+  "Evaluate Content folder usage and redundancy"
+  "Restore or remove week directory structure in book-src"
+  "Populate or remove empty placeholder report files"
+  "Review and update documentation files for consistency"
+  "Improve SUMMARY.md generation and book navigation"
+  "Comprehensive codebase audit and cleanup roadmap"
+)
+
+# Array of labels
+labels=(
+  "cleanup,documentation,scripts"
+  "cleanup,documentation,content-structure"
+  "cleanup,structure,decision-needed"
+  "cleanup,content,reports"
+  "documentation,cleanup,consistency"
+  "enhancement,user-experience,mdbook"
+  "epic,cleanup,planning"
+)
+
+# Create each issue
+for i in {1..7}; do
+  echo "Creating Issue #$i: ${titles[$i-1]}"
+
+  # Extract issue content from ISSUES_TO_CREATE.md
+  if [ $i -eq 7 ]; then
+    # Last issue goes to end of file
+    body=$(sed -n "/^## Issue #$i:/,\$p" ISSUES_TO_CREATE.md)
+  else
+    # Other issues go until next issue
+    next=$((i + 1))
+    body=$(sed -n "/^## Issue #$i:/,/^## Issue #$next:/p" ISSUES_TO_CREATE.md | head -n -1)
+  fi
+
+  # Create the issue
+  echo "$body" | gh issue create \
+    --title "${titles[$i-1]}" \
+    --label "${labels[$i-1]}" \
+    --body-file -
+
+  echo "✓ Issue #$i created"
+  echo ""
+
+  # Brief pause to avoid rate limiting
+  sleep 2
+done
+
+echo "All issues created successfully!"
+```
+
+Save this as `create_issues.sh`, make it executable with `chmod +x create_issues.sh`, and run it.
+
+## Issue Creation Checklist
+
+For each issue you create, verify:
+
+- [ ] Title matches the issue heading
+- [ ] All content from that issue section is included
+- [ ] Labels are added as specified
+- [ ] The issue number is visible in the created issue
+- [ ] Related issues are cross-referenced (you may need to edit and add links after all issues are created)
+
+## After Creating All Issues
+
+1. **Update Cross-References**
+   - Go back through each issue
+   - Update "Related Issues" sections with actual issue numbers
+   - Add links to related issues
+
+2. **Create Project Board (Optional)**
+   - Create a GitHub Project for "Codebase Cleanup"
+   - Add all 7 issues to the project
+   - Organize by priority/status
+
+3. **Assign and Prioritize**
+   - Assign issues to team members
+   - Set milestones if appropriate
+   - Add to project boards
+
+## Notes
+
+- The issues are designed to be created in order, as later issues reference earlier ones
+- Each issue is self-contained with full context
+- Issues #1-3 should be prioritized as they unblock other work
+- Issue #7 serves as an epic to track overall progress
+