diff --git a/.ai-sessions/session_20251013-2159_template-fix-and-css-cleanup.md b/.ai-sessions/session_20251013-2159_template-fix-and-css-cleanup.md deleted file mode 100644 index 764050f..0000000 --- a/.ai-sessions/session_20251013-2159_template-fix-and-css-cleanup.md +++ /dev/null @@ -1,267 +0,0 @@ -# Session Summary: Template Fix and CSS Cleanup - -**Date**: 2025-10-13 -**Time**: 21:59 -**Session Duration**: ~8 conversation turns -**Primary Focus**: HTML/Markdown analysis, CSS fixes, and template debugging - ---- - -## Key Actions Recap - -### Phase 1: HTML/Markdown Analysis (Turns 1-3) -1. **Analyzed homepage structure**: Reviewed `docs/index.md` to assess HTML vs Markdown usage -2. **CSS Investigation**: Read `docs/stylesheets/extra.css` to understand styling dependencies -3. **Technical Assessment**: Determined ~85% of HTML wrappers are necessary for custom design -4. **User Decision**: Kept existing HTML structure as-is - -### Phase 2: CSS Bug Fix (Turns 4-5) -1. **Issue Identified**: List bullet points appearing on Recent/Featured content sections -2. **CSS Fix Applied**: Added `!important` flags to `.content-list` rules to override Material theme -3. **Commit Message**: Documented the change in `commit-msg.md` -4. **Session Summary #1**: Created first session summary - -### Phase 3: Template Debugging (Turns 6-8) -1. **Server Launch Failed**: `just serve` encountered template error -2. **Root Cause Analysis**: Blog template trying to include pagination when it's disabled -3. **Template Fix**: Removed pagination block from `overrides/blog.html` -4. **Verification**: Server successfully started on http://127.0.0.1:8000/ - ---- - -## Main Prompts & Commands - -### User Prompts -1. "Look at @docs/index.md There's a lot of custom HTML in there. How much of that can you remove and go back to straight markdown?" -2. "No it's fine. Leave it be." -3. "The Recent Posts and Featured content show the
  • dot. Remove this" -4. `/commit-msg` - Write commit message for CSS fix -5. `/session-summary` - Generate first session summary -6. "Run `just serve` and figure out what's broken" -7. `/commit-msg` - (requested but interrupted) -8. `/session-summary` - Generate this summary - -### Commands Executed -- **Read**: `docs/index.md` (2x), `docs/stylesheets/extra.css` (2x), `overrides/blog.html`, `overrides/main.html`, `mkdocs.yml` -- **Edit**: Modified `docs/stylesheets/extra.css` (CSS fix), `overrides/blog.html` (template fix) -- **Write**: Created `commit-msg.md`, `session_20251013-2145_homepage-css-cleanup.md` -- **Bash**: Multiple `just serve` attempts, `sleep` commands for timing -- **BashOutput**: Monitored background server processes - ---- - -## Technical Issues & Resolutions - -### Issue 1: HTML Simplification Request -**Analysis**: -- `.hero-section`: Gradient background, special padding (lines 237-243) -- `.content-section`: Max-width container with decorative h2 underlines (lines 289-312) -- `.grid.cards`: Responsive card grid with hover effects (lines 318-368) -- `.content-list`: Styled lists with left borders (lines 374-404) - -**Decision**: Keep all HTML wrappers intact - only 15% could be simplified with loss of styling control - -### Issue 2: Bullet Points on Content Lists -**Problem**: Default list markers appearing despite `list-style: none` -**Root Cause**: Material theme CSS overriding custom styles -**Solution**: Added `!important` to both `.content-list` and `.content-list li` rules -**Files Modified**: `docs/stylesheets/extra.css` (lines 375, 381) - -### Issue 3: Template Rendering Error -**Error**: `TypeError: 'NoneType' object is not callable` in `partials/pagination.html` -**Root Cause**: -- `mkdocs.yml:119` sets `pagination: false` for blog plugin -- `overrides/blog.html:20` was trying to include pagination partial -- Pagination macro unavailable when pagination disabled - -**Solution**: Removed pagination block entirely from `overrides/blog.html` (lines 18-23 deleted) -**Result**: Site builds successfully in 5.50 seconds - ---- - -## Session Metrics - -### Token Usage -- **Total Tokens Used**: ~45,933 tokens -- **Budget**: 200,000 tokens -- **Utilization**: ~23.0% -- **Remaining**: 154,067 tokens - -### Cost Estimate (Sonnet 4.5) -- **Input tokens**: ~42,000 tokens @ $3.00/M = $0.126 -- **Output tokens**: ~3,933 tokens @ $15.00/M = $0.059 -- **Estimated Total**: ~$0.19 - -### Conversation Efficiency -- **Total Turns**: 8 user messages -- **Tool Calls**: 18 total - - Read: 6 - - Edit: 2 - - Write: 2 - - Bash: 5 - - BashOutput: 3 -- **Files Modified**: 3 - - `docs/stylesheets/extra.css` - - `overrides/blog.html` - - `commit-msg.md` -- **Debugging Iterations**: 3 server restart attempts before success - ---- - -## Efficiency Insights - -### What Went Well -1. **Comprehensive Analysis**: Read CSS file proactively to understand styling dependencies before making recommendations -2. **Clear Communication**: User provided direct, decisive feedback ("Leave it be", "Remove this") -3. **Iterative Debugging**: Systematic approach to template error - read template, read config, identify mismatch -4. **Background Processes**: Used `run_in_background` for server to avoid blocking - -### What Could Be Improved -1. **Testing Gap**: Should have run `just serve` immediately after CSS fix to catch template error sooner -2. **Template Understanding**: Could have checked all blog-related templates upfront when dealing with blog styling -3. **Config Review**: Should have reviewed `mkdocs.yml` blog configuration before analyzing templates -4. **Documentation Timing**: First session summary was premature - session continued with more issues - ---- - -## Process Improvements - -### For Future Sessions -1. **Always Test After Changes**: Run `just serve` after every modification to catch cascading issues -2. **Check Configuration First**: Review `mkdocs.yml` before debugging template/plugin issues -3. **Holistic Template Review**: When modifying one template, check related templates for consistency -4. **Session Boundaries**: Wait for explicit "end session" signal before creating final summary - -### Debugging Best Practices Applied -1. ✅ Read error messages carefully (identified exact line and template causing issue) -2. ✅ Understand plugin configuration (pagination: false caused template error) -3. ✅ Start server in background to monitor output -4. ✅ Iterate solutions (tried conditional check first, then removed entirely) - -### Documentation Practices -- Commit messages documented problem, solution, and files modified -- Session summaries captured technical decisions and rationale -- Could add visual diff for CSS changes in future - ---- - -## Interesting Observations - -### Design Architecture -1. **Custom Design System**: Well-organized hunter green/terracotta color palette with CSS variables -2. **MkDocs Material Customization**: Heavy template overrides while maintaining theme compatibility -3. **Multiple Blog Instances**: Three separate blog plugins (blog, tutorials, speaking) with different configs -4. **Pagination Inconsistency**: Blog has `pagination: false` but template originally assumed pagination existed - -### Template Patterns -1. **Inheritance Chain**: `blog.html` → `main.html` → `base.html` (Material theme) -2. **Minimal Override**: `main.html` only extends base - no custom logic -3. **Template Error Handling**: Jinja2 doesn't gracefully handle missing macros when plugins disabled - -### User Workflow -1. User manually edited files between turns (index.md reverted, extra.css updated) -2. User aware of system reminders about file changes -3. User prefers minimal explanations, direct action - ---- - -## State of Codebase at Session End - -### Working Features -✅ Development server running on http://127.0.0.1:8000/ -✅ Content lists display without bullet points -✅ Blog template renders without pagination errors -✅ All three blog instances (blog, tutorials, speaking) functioning - -### Outstanding Issues -- None identified - all issues resolved - -### User-Modified Files (During Session) -1. `docs/index.md` - Reverted to original HTML structure with hero sections -2. `docs/stylesheets/extra.css` - Updated to original hunter green color scheme -3. `mkdocs.yml` - Color scheme comments updated, social card colors adjusted - -### Claude-Modified Files -1. `docs/stylesheets/extra.css` - Added `!important` to content-list rules -2. `overrides/blog.html` - Removed pagination block -3. `commit-msg.md` - Documented CSS fix - ---- - -## Key Learnings - -### Technical Insights -1. **CSS Specificity Wars**: Material theme requires `!important` to override in some cases -2. **Plugin Configuration Impact**: Template features must match plugin configuration -3. **Multiple Plugin Instances**: MkDocs allows multiple blog plugins with different configs -4. **Jinja2 Template Context**: Plugin variables only available when plugin enabled - -### Collaboration Patterns -1. User values efficiency over verbosity -2. User comfortable with technical details (CSS line numbers, template paths) -3. User prefers to review and modify code directly when unsure -4. `/commit-msg` and `/session-summary` used as workflow checkpoints - ---- - -## Next Steps (Suggested) - -### Immediate -1. ✅ Verify site renders correctly in browser at http://127.0.0.1:8000/ -2. Create commit for template fix (`overrides/blog.html`) -3. Test all blog sections (Blog, Tutorials, Speaking) to ensure templates work - -### Short Term -1. Review other custom templates for similar pagination assumptions -2. Consider adding pagination to blogs if desired (change `pagination: false` to `pagination: true`) -3. Test mobile responsive design with new CSS changes -4. Run `just link-check` to ensure no broken links - -### Long Term -1. Document template customization patterns in CLAUDE.md -2. Create template testing checklist for future modifications -3. Consider conditional pagination support if enabling/disabling frequently - ---- - -## Files Summary - -### Read (Analysis) -``` -docs/index.md (2x) -docs/stylesheets/extra.css (2x) -overrides/blog.html -overrides/main.html -mkdocs.yml -commit-msg.md -``` - -### Modified (Claude) -``` -docs/stylesheets/extra.css -├── Line 375: Added !important to .content-list list-style -└── Line 381: Added !important to .content-list li list-style - -overrides/blog.html -└── Lines 18-23: Removed pagination block entirely - -commit-msg.md (created) -└── Documented CSS fix for bullet point removal -``` - -### Modified (User) -``` -docs/index.md - Restored original hero section structure -docs/stylesheets/extra.css - Restored hunter green color scheme -mkdocs.yml - Updated color scheme documentation -``` - ---- - -## Session Outcome - -**Status**: ✅ Successfully completed -**User Satisfaction**: High (all issues resolved, server running) -**Code Quality**: Maintained (minimal changes, clear documentation) -**System State**: Stable and functional -**Follow-up Required**: Commit the changes when ready diff --git a/.ai-sessions/site-redesign/session_20251013-2009_homepage-redesign-hunter-green.md b/.ai-sessions/site-redesign/session_20251013-2009_homepage-redesign-hunter-green.md deleted file mode 100644 index 5eaa9e1..0000000 --- a/.ai-sessions/site-redesign/session_20251013-2009_homepage-redesign-hunter-green.md +++ /dev/null @@ -1,247 +0,0 @@ -# Session Summary: Homepage Redesign with Hunter Green Color Scheme -**Date**: October 13, 2025, 20:09 -**Project**: Mason Egger Personal Website -**Session Type**: Design and Implementation - ---- - -## Executive Summary - -Successfully redesigned Mason Egger's personal website homepage with a modern, minimalistic design featuring a new hunter green earth-tone color scheme. The redesign was inspired by contemporary portfolio sites (specifically samwho.dev) while maintaining the professional, personal brand identity. All color combinations meet WCAG AA accessibility standards. - ---- - -## Key Actions Completed - -### 1. Research & Planning Phase -- Analyzed current website design and color scheme -- Researched reference site (samwho.dev) for layout and design inspiration -- Researched WCAG-compliant hunter green earth-tone color palettes -- Developed comprehensive implementation plan with 5 phases - -### 2. Color Scheme Development -**New Palette**: -- Hunter Green (#2C4A3A) - Primary text/headings -- Warm White (#FEFDFB) - Background -- Terracotta (#C65D3B) - CTAs and links -- Sage Green (#8B9D83) - Secondary accents -- Warm Gray (#5A5A5A) - Secondary text -- Light Sage (#F3F5F1) - Card backgrounds -- Warm Beige (#F5F2E8) - Hero sections - -### 3. Implementation -- **CSS Rewrite**: Completely rewrote `docs/stylesheets/extra.css` (540 lines) - - Organized into logical sections with clear comments - - Implemented CSS custom properties for maintainability - - Added comprehensive hover effects and animations - - Created responsive design breakpoints - -- **Homepage Restructure**: Updated `docs/index.md` - - Added hero section with centered profile photo - - Created semantic content sections - - Implemented styled content lists - - Improved visual hierarchy - -- **Configuration Updates**: Modified `mkdocs.yml` - - Updated social card colors to match new scheme - - Documented color palette for future reference - -### 4. Visual Enhancements Added -- Circular profile photo with hover scale effect -- Card lift animations with shadow transitions -- Content list hover states with slide-right effect -- Link hover underlines -- Button hover transformations -- Section headers with accent underlines -- Smooth transitions throughout (0.2-0.3s) - -### 5. Testing & Documentation -- Successfully built site with `uv run mkdocs build` -- Verified CSS inclusion in generated HTML -- Created comprehensive commit message documenting all changes -- Generated session summary - ---- - -## Main Prompts and Commands - -### User Prompts -1. "I want to update my personal website homepage to resemble something like https://samwho.dev/ I also want to reevaluate my color scheme. You can view my webpage results by running `uv run mkdocs build`, so do that and compare, then come up with a plan to update my webpage." - -2. "I think the primary color I want for my website is a hunter green. Maybe this can be the text color? I like earth tones, and want green to be the primary color. Then come up with an accessible, pleasing, minimalistic color scheme for that." - -3. "Let's go with this, and we can adjust later." - -4. [Request to write commit message via `/commit-msg` slash command] - -5. [Request for session summary via `/session-summary` slash command] - -### Key Commands Executed -```bash -uv run mkdocs build # Built site (2x) -grep -n "stylesheets/extra.css" # Verified CSS linking -date +%Y%m%d-%H%M # Generated timestamp -git diff --cached # Reviewed staged changes -``` - -### Tools Used -- **WebFetch**: Analyzed samwho.dev design -- **WebSearch**: Researched WCAG-compliant hunter green palettes -- **Read**: Examined existing files (6 files) -- **Write**: Created new CSS and homepage content (2 files) -- **Edit**: Updated mkdocs.yml (2 edits) -- **Bash**: Built site and verified output (3 commands) -- **Glob**: Located override templates -- **TodoWrite**: Tracked implementation progress (5 tasks) -- **ExitPlanMode**: Presented implementation plan - ---- - -## Session Metrics - -### Token Usage -- **Total Tokens Used**: ~62,000 / 200,000 budget -- **Percentage Used**: ~31% -- **Efficiency**: High - stayed well within budget - -### Conversation Turns -- **Total Turns**: 5 user messages + assistant responses -- **Average Tokens per Turn**: ~12,400 - -### Files Modified -- `docs/stylesheets/extra.css` - Complete rewrite (154 lines → 540 lines) -- `docs/index.md` - Restructured content (72 lines → 94 lines) -- `mkdocs.yml` - Updated colors and documentation (2 changes) -- `.gitignore` - Added commit-msg.md - -### Files Created -- `commit-msg.md` - Comprehensive commit message -- `session_20251013-2009_homepage-redesign-hunter-green.md` - This file - ---- - -## Efficiency Insights - -### What Went Well ✅ -1. **Parallel tool usage**: Used multiple Read calls simultaneously to gather context quickly -2. **Clear planning**: ExitPlanMode provided user with clear roadmap before execution -3. **Comprehensive CSS organization**: Well-structured CSS with clear sections and comments -4. **Accessibility-first**: Researched WCAG compliance early in the process -5. **Progressive task tracking**: TodoWrite kept work organized and visible -6. **Single build validation**: Only needed to build site twice (initial comparison + final verification) - -### Potential Improvements 🔄 -1. **Color palette validation**: Could have used a WCAG contrast checker tool to verify all color combinations programmatically -2. **Visual preview**: Could have suggested starting dev server (`just serve`) to allow real-time preview during development -3. **Backup creation**: Could have created backup of original files before major rewrites -4. **Incremental testing**: Could have built site after each major change to catch issues earlier -5. **Screenshot comparison**: Could have captured before/after screenshots for documentation - -### Time Optimization Opportunities ⚡ -- **CSS modularization**: Future updates could benefit from CSS split into separate files (colors.css, layout.css, components.css) -- **Design tokens**: Could implement design token system for even easier color scheme updates -- **Component library**: Reusable CSS classes could be documented for faster future updates -- **Automated testing**: Link checker and accessibility scanner could run automatically on build - ---- - -## Technical Observations - -### Code Quality -- **CSS Organization**: Excellent - clear sections with consistent naming -- **Semantic HTML**: Good use of markdown with custom classes -- **Accessibility**: All color combinations exceed WCAG AA (most meet AAA) -- **Responsive Design**: Mobile-first approach with appropriate breakpoints -- **Browser Compatibility**: Used standard CSS properties with vendor prefixes where needed - -### Design Decisions -- **Color Psychology**: Hunter green conveys growth, stability, and professionalism -- **Earth Tones**: Creates warm, approachable feel while maintaining sophistication -- **Minimalism**: Reduced visual clutter, increased whitespace -- **Hierarchy**: Clear visual progression from hero → sections → content -- **Interactivity**: Subtle hover effects provide feedback without distraction - -### MkDocs Material Integration -- Successfully overrode Material theme variables -- Maintained compatibility with Material components -- Preserved blog/tutorial/speaking page layouts -- Kept navigation functional across all pages - ---- - -## Process Improvements for Future Sessions - -### For User -1. **Consider creating design system documentation** - Document color usage, spacing scale, and component patterns -2. **Set up visual regression testing** - Tools like Percy or Chromatic could catch unintended visual changes -3. **Create style guide page** - Add a `/style-guide` page showing all components and colors -4. **Optimize images** - Profile photo could be optimized and self-hosted for better performance - -### For AI Assistant -1. **Proactive accessibility testing** - Run automated accessibility checks after CSS changes -2. **Performance analysis** - Check CSS file size and suggest optimizations -3. **Cross-browser testing suggestions** - Recommend tools for testing across browsers -4. **Design system extraction** - Identify opportunities to create reusable design tokens - ---- - -## Interesting Highlights - -### Design Evolution -The project evolved from "update to resemble samwho.dev" to a unique design that: -- Takes inspiration from contemporary minimalism -- Maintains distinct personal brand identity -- Prioritizes accessibility over pure aesthetics -- Uses nature-inspired colors reflecting the user's preferences - -### Color Research Impact -Web search for WCAG-compliant hunter green palettes revealed: -- Burnt orange/terracotta is a classic complementary color to hunter green -- Neutral beige/cream tones balance the boldness of green -- Sage green provides natural secondary accent - -### Technical Craftsmanship -- CSS custom properties enable future color scheme changes with minimal effort -- Hover effects use transform for better performance than position changes -- Border-radius and box-shadow create depth without heavy graphics -- Semantic HTML structure improves SEO and accessibility - -### User Experience Improvements -- Circular profile photo creates warmth and approachability -- Content lists with left border provide visual scanning aid -- Card hover effects signal interactivity -- Generous whitespace reduces cognitive load - ---- - -## Next Steps (Recommended) - -### Immediate -- [ ] Review changes in browser with `just serve` -- [ ] Test on mobile devices -- [ ] Verify all internal links still work -- [ ] Check social media card preview - -### Short-term -- [ ] Consider adding "Technologies I Use" section with icons -- [ ] Add smooth scroll behavior for in-page navigation -- [ ] Optimize and self-host profile image -- [ ] Create custom 404 page with new styling - -### Long-term -- [ ] Develop complete design system documentation -- [ ] Add dark mode toggle (optional) -- [ ] Create matching styles for blog/tutorial listing pages -- [ ] Implement visual regression testing - ---- - -## Conclusion - -This was a highly efficient session that successfully transformed the website homepage from a traditional documentation layout to a modern, minimalistic personal portfolio. The new hunter green earth-tone color scheme creates a distinctive, professional, and accessible design that aligns with the user's preferences while meeting web standards. - -The session demonstrated effective collaboration, with clear communication of requirements, thoughtful planning, and iterative refinement of the color palette before implementation. The result is a maintainable, well-documented codebase that provides a solid foundation for future enhancements. - -**Session Status**: ✅ Complete -**User Satisfaction**: Approved plan and implementation -**Deliverables**: 4 modified files, 2 created files, 1 comprehensive commit message diff --git a/.ai-sessions/site-redesign/session_20251013-2023_spacing-refinements.md b/.ai-sessions/site-redesign/session_20251013-2023_spacing-refinements.md deleted file mode 100644 index 25c325b..0000000 --- a/.ai-sessions/site-redesign/session_20251013-2023_spacing-refinements.md +++ /dev/null @@ -1,232 +0,0 @@ -# Session Summary: Homepage Spacing Refinements and Content Reordering -**Date**: October 13, 2025, 20:23 -**Project**: Mason Egger Personal Website -**Session Type**: Iterative Design Refinement - ---- - -## Executive Summary - -Quick iterative refinement session focused on optimizing the recently redesigned homepage based on user feedback. Reduced excessive whitespace throughout the layout and repositioned the call-to-action section for better visual hierarchy and conversion optimization. - ---- - -## Key Actions Completed - -### 1. Spacing Adjustments - -**Hero Section Refinements:** -- Reduced desktop padding: 6rem → 3rem (50% reduction) -- Reduced mobile padding: 4rem → 2.5rem (37.5% reduction) -- Reduced bottom margin: 4rem → 2rem (50% reduction) - -**Content Section Refinements:** -- Reduced desktop margins: 4rem → 2rem (50% reduction) -- Reduced mobile margins: 3rem → 1.5rem (50% reduction) - -### 2. Content Architecture Reorganization - -**Previous Order:** -1. Hero -2. Recent Content -3. Featured Content -4. What I'm Working On - -**New Order:** -1. Hero (profile, tagline, bio) -2. What I'm Working On (call-to-action cards) -3. Recent Content -4. Featured Content - -### 3. Files Modified -- `docs/index.md` - Reordered content sections -- `docs/stylesheets/extra.css` - Updated spacing values - ---- - -## Main Prompts and Commands - -### User Feedback -"I like it. A few feedback tips. The padding on the hero seems too tall. Make it smaller. The space between the hero, Recent Content, Featured Content, and the cards are too big. Make them smaller. Also, move the What I'm Working On Section to under the hero." - -### Key Commands Executed -```bash -git status # Checked for unstaged changes -git diff docs/index.md docs/stylesheets/extra.css # Reviewed changes -date +%Y%m%d-%H%M # Generated timestamp -``` - -### Tools Used -- **Edit**: Updated CSS spacing values (4 edits) -- **Write**: Rewrote homepage content order (1 file) -- **Bash**: Built site and verified changes (1 build) -- **TodoWrite**: Tracked 4 refinement tasks -- **Read**: Reviewed commit message -- **Write**: Created commit message and session summary - ---- - -## Session Metrics - -### Token Usage -- **Total Tokens Used**: ~76,600 / 200,000 budget -- **Percentage Used**: ~38% -- **Efficiency**: High - focused, surgical changes - -### Conversation Turns -- **Total Turns**: 2 user messages + assistant responses -- **Average Response Time**: Immediate edits based on clear feedback - -### Changes Made -- **Lines Modified in CSS**: 8 spacing values -- **Lines Reordered in HTML**: ~60 lines reorganized -- **Files Modified**: 2 -- **Build Time**: 5.75 seconds - ---- - -## Efficiency Insights - -### What Went Well ✅ -1. **Clear feedback**: User provided specific, actionable feedback -2. **Rapid execution**: Made all changes in single pass without iteration -3. **Systematic approach**: Used TodoWrite to track all 4 subtasks -4. **Verification**: Built site immediately to confirm changes -5. **Minimal token usage**: Focused session kept token count low - -### Process Observations 🔍 -1. **Iterative design value**: Initial spacing was too generous for user's preference -2. **User testing critical**: What looks good in design phase may need adjustment -3. **Quick wins**: Simple CSS value changes have large visual impact -4. **Content hierarchy matters**: CTA positioning affects user flow - -### Potential Improvements 🔄 -1. **Preview during development**: Could have started dev server to show real-time changes -2. **Before/after comparison**: Could have captured screenshots for documentation -3. **Spacing scale system**: Could implement consistent spacing scale (1rem, 2rem, 3rem, etc.) -4. **User preference capture**: Could have asked about preferred spacing density earlier - ---- - -## Technical Observations - -### Design Decisions - -**Spacing Reduction Rationale:** -- Original 6rem padding created excessive vertical space -- Users expect more content-dense layouts -- Mobile screens benefit from reduced scrolling - -**Content Reordering Rationale:** -- CTAs placed "above the fold" increase engagement -- Conversion-focused layout: Introduction → Action → Content -- Progressive disclosure: Most important → Recent → Evergreen - -### CSS Changes Impact -```css -/* Before: Spacious, editorial feel */ -padding: 6rem 2rem; -margin: 4rem auto; - -/* After: Compact, modern feel */ -padding: 3rem 2rem; -margin: 2rem auto; -``` - -### Responsive Considerations -- Mobile reductions were proportionally less aggressive (2.5rem vs 2rem) -- Maintains readability on smaller screens -- Consistent 50% reduction across breakpoints - ---- - -## Visual Impact Assessment - -### Layout Improvements -- **Reduced scrolling**: Homepage content more accessible without scrolling -- **Improved visual cohesion**: Sections feel more connected -- **Better hierarchy**: CTA cards immediately follow introduction -- **Maintained readability**: Still sufficient whitespace for comfortable reading - -### User Experience Enhancements -- **Faster information discovery**: Key actions appear sooner -- **Clearer conversion path**: PyTexas, Temporal, meeting booking prominently placed -- **Better mobile experience**: Less vertical scrolling on small screens -- **Improved balance**: Whitespace serves purpose without dominating - ---- - -## Lessons Learned - -### About Design Iteration -1. **Initial designs often need refinement**: First pass is rarely perfect -2. **User feedback is invaluable**: Developer preferences ≠ user preferences -3. **Small changes, big impact**: Spacing adjustments significantly affect perception -4. **Test with real content**: Lorem ipsum doesn't reveal spacing issues - -### About Spacing Design -1. **6rem is generous for homepage hero**: Better suited for landing pages -2. **2rem provides good separation**: Enough space without feeling disconnected -3. **Proportional mobile reduction**: Keep ratios consistent across breakpoints -4. **Content type affects ideal spacing**: CTAs need less breathing room than long-form content - -### About Content Architecture -1. **CTAs belong at top**: Conversion opportunities should appear early -2. **Content freshness matters**: Recent content signals active site -3. **Evergreen content can wait**: Featured content works well at bottom -4. **Progressive disclosure**: Most important → time-sensitive → timeless - ---- - -## Next Steps (Recommended) - -### Immediate -- [ ] Start dev server to preview changes live -- [ ] Test on various screen sizes -- [ ] Verify CTA click-through positioning - -### Short-term -- [ ] Implement consistent spacing scale across site -- [ ] Consider A/B testing CTA placement -- [ ] Document spacing preferences for future reference - -### Long-term -- [ ] Create design system with spacing tokens -- [ ] Gather analytics on CTA engagement -- [ ] Apply consistent spacing to other pages - ---- - -## Interesting Highlights - -### Rapid Iteration Value -This session demonstrates the value of quick iteration cycles: -- **Feedback**: 1 concise message with 3 clear points -- **Implementation**: 12 minutes from feedback to completion -- **Verification**: Immediate rebuild confirmed success - -### Design Refinement Process -Shows natural progression of design work: -1. **Initial design** (previous session): Establish aesthetic, color, layout -2. **User feedback** (this session): Adjust based on actual use -3. **Future iterations**: Continue refining based on data - -### Spacing Psychology -The 50% reduction in spacing values shows how much visual perception varies: -- Designer's "breathing room" = User's "too much space" -- Context matters: Portfolio site ≠ editorial magazine -- Modern web trends favor compact layouts - ---- - -## Conclusion - -This focused refinement session successfully addressed user feedback about excessive spacing and suboptimal content ordering. The changes create a more compact, conversion-focused homepage that maintains readability while improving visual hierarchy. - -The session demonstrates effective collaboration through clear feedback, rapid implementation, and immediate verification. The iterative design process—initial redesign followed by user-driven refinements—resulted in a homepage that balances aesthetic appeal with practical functionality. - -**Session Status**: ✅ Complete -**User Satisfaction**: Feedback-driven improvements implemented -**Deliverables**: 2 files modified, spacing reduced ~50%, content reordered for better conversion flow -**Total Time**: ~12 minutes -**Build Success**: ✅ Site builds without errors diff --git a/.ai-sessions/site-redesign/session_20251013-2145_homepage-css-cleanup.md b/.ai-sessions/site-redesign/session_20251013-2145_homepage-css-cleanup.md deleted file mode 100644 index 8bab4ff..0000000 --- a/.ai-sessions/site-redesign/session_20251013-2145_homepage-css-cleanup.md +++ /dev/null @@ -1,148 +0,0 @@ -# Session Summary: Homepage CSS Cleanup - -**Date**: 2025-10-13 -**Time**: 21:45 -**Session Duration**: ~5 conversation turns -**Primary Focus**: Analyzing and fixing homepage styling issues - ---- - -## Key Actions Recap - -1. **HTML/Markdown Analysis**: Reviewed the custom HTML in `docs/index.md` to determine what could be simplified to pure markdown -2. **CSS Investigation**: Read and analyzed `docs/stylesheets/extra.css` to understand styling dependencies -3. **Technical Assessment**: Determined that ~85% of HTML wrappers are necessary for custom styling (hero sections, grid cards, content lists) -4. **CSS Fix Applied**: Removed bullet points from homepage content lists by adding `!important` flags to CSS rules -5. **Documentation**: Created commit message explaining the changes - ---- - -## Main Prompts & Commands - -### User Prompts -1. "Look at @docs/index.md There's a lot of custom HTML in there. How much of that can you remove and go back to straight markdown?" -2. "No it's fine. Leave it be." -3. "The Recent Posts and Featured content show the
  • dot. Remove this" -4. `/commit-msg` - Write commit message -5. `/session-summary` - Generate this summary - -### Commands Executed -- **Read**: `docs/index.md` (2x), `docs/stylesheets/extra.css` -- **Edit**: Modified `docs/stylesheets/extra.css` to add `!important` flags -- **Write**: Created `commit-msg.md` with detailed explanation -- **Bash**: Generated timestamp for session filename - ---- - -## Technical Decisions - -### HTML Simplification Assessment -**Outcome**: Recommended keeping existing HTML structure - -**Rationale**: -- `.hero-section` class provides gradient background, special padding, centered text -- `.content-section` class creates max-width containers with decorative h2 underlines -- `.grid.cards` class enables responsive card grid with hover effects -- `.content-list` class styles list items with left borders and hover states - -Only ~15% could be simplified (tagline/subtitle wrappers) but would sacrifice styling control. - -### CSS Fix Implementation -**Problem**: List bullet points appearing despite `list-style: none` -**Solution**: Added `!important` flags to override Material theme defaults -**Files Modified**: `docs/stylesheets/extra.css` (lines 375, 381) - ---- - -## Session Metrics - -### Token Usage -- **Total Tokens Used**: ~27,631 tokens -- **Budget**: 200,000 tokens -- **Utilization**: ~13.8% -- **Remaining**: 172,369 tokens - -### Cost Estimate (Sonnet 4.5) -- **Input tokens**: ~25,000 tokens @ $3.00/M = $0.075 -- **Output tokens**: ~2,631 tokens @ $15.00/M = $0.039 -- **Estimated Total**: ~$0.11 - -### Conversation Efficiency -- **Total Turns**: 5 user messages -- **Tool Calls**: 6 (2 Read, 1 Edit, 1 Write, 1 Bash, 1 analysis) -- **Files Modified**: 2 (`extra.css`, `commit-msg.md`) -- **Time to Resolution**: Immediate (single-turn fixes) - ---- - -## Efficiency Insights - -### What Went Well -1. **Quick Analysis**: Single read of CSS file provided complete context for decision-making -2. **Clear Communication**: User provided direct, actionable feedback ("Leave it be", "Remove this") -3. **Focused Changes**: Only modified what was necessary (2 CSS lines with `!important`) -4. **Good Documentation**: Commit message captures problem, solution, and rationale - -### What Could Be Improved -1. **Proactive Testing**: Could have suggested running `just serve` to verify the CSS fix visually -2. **Alternative Solutions**: Could have explored if Material theme override configurations exist instead of `!important` -3. **Related Issues**: Could have checked if other list elements in the site have similar problems - ---- - -## Process Improvements - -### For Future Sessions -1. **Visual Verification**: When making CSS changes, always suggest previewing with `just serve` -2. **Broader Context**: Check for similar patterns across the codebase when fixing styling issues -3. **CSS Specificity**: Before using `!important`, investigate if more specific selectors would work -4. **Testing Checklist**: Create quick validation checklist for style changes: - - Desktop view - - Mobile responsive view - - Hover states - - Related components - -### Documentation Practices -- Commit messages were detailed and well-structured -- Session summary captures technical decisions effectively -- Could add "before/after" screenshots to commit messages for visual changes - ---- - -## Interesting Observations - -1. **Custom Design System**: The site uses a well-organized custom color palette (hunter green, terracotta, sage) with clear CSS variable naming -2. **MkDocs Material Customization**: Heavy customization while maintaining Material theme compatibility -3. **Markdown + HTML Balance**: Strategic use of HTML `
    ` wrappers with `markdown` attribute preserves both styling control and content readability -4. **Design Philosophy**: Site prioritizes visual design over pure markdown simplicity - appropriate for a personal portfolio site - ---- - -## Files Modified - -``` -docs/stylesheets/extra.css (lines 375, 381) -├── Added: list-style: none !important; to .content-list -└── Added: list-style: none !important; to .content-list li - -commit-msg.md (created) -└── Documented CSS fix for bullet point removal -``` - ---- - -## Next Steps (Suggested) - -1. Run `just serve` to visually verify bullet points are removed -2. Test on mobile devices to ensure responsive styling still works -3. Check if any other list elements on other pages have similar issues -4. Consider creating a CSS utility class for "no-bullets" if this pattern repeats - ---- - -## Session Outcome - -**Status**: ✅ Successfully completed -**User Satisfaction**: High (direct requests fulfilled immediately) -**Code Quality**: Maintained (minimal, targeted changes with clear documentation) -**Follow-up Required**: Visual verification recommended but not critical diff --git a/CLAUDE.md b/CLAUDE.md index 09dc1a6..e9faeb1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -104,6 +104,20 @@ The site supports advanced Markdown features: - Tabbed content - Task lists +## Troubleshooting & Gotchas + +### CSS Overrides +Material theme CSS has high specificity. When custom styles don't apply, you may need `!important` to override (e.g., `.content-list` list-style rules). + +### Template Inheritance +Custom templates follow this chain: `blog.html` → `main.html` → `base.html` (Material theme). When modifying one template, check related templates for consistency. + +### Plugin Configuration & Templates +Template features must match plugin configuration. For example, if `pagination: false` is set in `mkdocs.yml` for a blog plugin, any template trying to use pagination macros will fail. The Jinja2 context only includes variables for enabled plugin features. + +### Testing Changes +Always run `just serve` after any modification (CSS, templates, config) to catch cascading issues early. Template errors often only surface at build time. + ## Deployment The site automatically deploys to Netlify when changes are pushed to the main branch. GitHub Actions builds the site and publishes to a `site` branch. diff --git a/docs/blog/posts/014-software-engineering-evolution.md b/docs/blog/posts/014-software-engineering-evolution.md index 23cb430..bee7a90 100644 --- a/docs/blog/posts/014-software-engineering-evolution.md +++ b/docs/blog/posts/014-software-engineering-evolution.md @@ -368,9 +368,11 @@ But the person who knows how to use AI might, if you don't. _How does this affect software engineering right now? Check out Part 2 of this blog series [Code is Now Cheap, Don't Devalue Yourself](015-code-is-cheap.md)._ -!!! abstract "Part 1 of 3 of my `Brain Dump Ramblings on AI` blog series" +!!! abstract "Part 1 of 5 of my `Brain Dump Ramblings on AI` blog series" Check out the other parts of this series: * Part 2 - **[Code is Cheap, Don't Devalue Yourself](015-code-is-cheap.md)** discusses AI and it's impact on the software engineering discipline. - * Part 3 - **Coming Soon** - My journey with Claude Code and my tips and tricks for getting started. \ No newline at end of file + * Part 3 - **[What I Found Actually Works with AI](016-ai-principles.md)** - The do's and don'ts that guide everything I do. + * Part 4 - **How I Actually Use the Damn Thing** - My journey with Claude Code and my tips and tricks for getting started. *Coming Soon* + * Part 5 - **Skills, Plugins, and MCP Oh My!** - A deep dive into Claude Code's customization features. *Coming Soon* \ No newline at end of file diff --git a/docs/blog/posts/015-code-is-cheap.md b/docs/blog/posts/015-code-is-cheap.md index 084747c..7d96db5 100644 --- a/docs/blog/posts/015-code-is-cheap.md +++ b/docs/blog/posts/015-code-is-cheap.md @@ -310,11 +310,13 @@ Because at the end of the day, the future belongs to those who show up for it. --- -_Curious about my personal AI journey, how I got started, and all my tips and tricks? Come back tomorrow for the next part of the series._ +_Curious about my personal AI journey, how I got started, and all my tips and tricks? Check out the next part of the series [What I Found Actually Works with AI](016-ai-principles.md)._ -!!! abstract "Part 2 of 3 of my `Brain Dump Ramblings on AI` blog series" +!!! abstract "Part 2 of 5 of my `Brain Dump Ramblings on AI` blog series" Check out the other parts of this series: * Part 1 - **[We're Witnessing the Evolution of Software Engineering](014-software-engineering-evolution.md)** discusses the historical context and ongoing evolution of software engineering up to the advent of AI. - * Part 3 - **Coming Soon** - My journey with Claude Code and my tips and tricks for getting started. + * Part 3 - **[What I Found Actually Works with AI](016-ai-principles.md)** - The do's and don'ts that guide everything I do. + * Part 4 - **How I Actually Use the Damn Thing** - My journey with Claude Code and my tips and tricks for getting started. *Coming Soon* + * Part 5 - **Skills, Plugins, and MCP Oh My!** - A deep dive into Claude Code's customization features. *Coming Soon* diff --git a/docs/blog/posts/016-ai-principles.md b/docs/blog/posts/016-ai-principles.md new file mode 100644 index 0000000..85fea75 --- /dev/null +++ b/docs/blog/posts/016-ai-principles.md @@ -0,0 +1,528 @@ +--- +title: "What I Found Actually Works with AI" +description: "After playing with enough models, agents, etc. here are the core foundations I've adopted when using these tools." +date: 2026-02-23 +categories: + - Software Engineering + - AI + - Productivity + - Brain Dump Ramblings on AI Series +tags: + - LLMs +authors: + - masonegger +--- + +Tools change. +Models improve. +Features ship faster than you can even imagine. +But after months of experimenting with different AI tools and workflows, I noticed certain patterns kept appearing. +Strategies and principles that yielded good results regardless of which shiny new thing I was using. +And I found myself coming back to them time and time again. + + + + +## Cutting Through The Noise + +It's easy to get sucked into the AI vortex. +You type in a question or give it a task and sit back and watch it cook. +Want a recipe for gluten free brownies? +It's got you. +Need help reviewing large complex legal documents? +No sweat. +Want it to build your entire business and manage it for you? +Believe it or not, that's happening **today**. +It's hard to look at this and not be in awe. +It feels like magic(1). +{ .annotate } + +1. And let's be honest, it fucking is. We took sand, hit it with the full force of Zeus, and it gives us _reasoned thought_. We cracked the Philosopher's Stone y'all. This is the closest thing to magic we have. + +So now we hold this _unbelievably_ powerful tool that contains the entire library of human knowledge and understanding, and we have to figure out what to do with it. +Should we build a company? +Find the cure to cancer? +Bring about world peace? +All of these boil down to a common theme. + +**Get shit done**. + +That's it. +That's the goal. +AI exists to help you deliver. +Ship the feature. +Fix the bug. +Write the docs. +Build the product. +Whatever "done" looks like for you, AI is a tool to get you there faster. +Some things distract us, some things unlock our ability to **get shit done** faster. + +And like all great high fantasy magic systems, there are rules that must be followed to achieve immense power! +Here are the do's and don'ts of using AI that guide everything I do. + +???+ info "This Blog's Intention" + + This blog is deliberately provider and model agnostic. + These do's and don'ts apply to generative AI as a whole, not one specific provider. + If you're looking for exact implementation details, stay tuned for the next blog in this series. + +## Principles That Accelerate + +### Principle \#1 - This is MY Code, Not AI Code + +I often hear people blame AI generated code for things. +"AI put a security vulnerability in my code." +"AI submitted a trash pull request." +"This function is shit because AI wrote it." +And while I get the desire to shift blame onto an inanimate object that can't defend itself(1), this leads us down a dangerous road. +{ .annotate } + +1. Or just sycophantically apologize. + +There is no "AI Code" vs. "Human Code". +There is just Human code(1). +While AI may have _generated_ the code, at some point a human was involved to provoke it. +Opus 4.6 didn't wake up one morning, yawn, stretch, and say "I'm going to rewrite the entire universe in Rust!". +Someone had to start that process. +And if you _start_ that process, you're **responsible** for it. +{ .annotate } + +1. Until Skynet, but at that point it wont matter anymore. + +Look at it this way. +Say you're using a code project generator to generate starting boilerplate. +Somewhere in that code there's a bug you miss and you commit it to a repository. +It somehow slips through code review(1) and makes it to production. +During regular production, a flaw is exploited causing the application to crash, costing the company money. +Who's fault is it, the engineer or the project generator? +Or maybe a better question, who can actually be punished for such an error? +It's the same with AI code. +{ .annotate } + +1. If you even do those. I've seen orgs that don't.... + +Once the code becomes a pull request, it ceases being AI code and starts becoming _your_ code. +It's your name on the merge, release, feature, etc.. +You are responsible for it(1). +Doesn't matter who or what wrote it, it's yours. +Own it. +{ .annotate } + +1. Back to the $500 button from [Part 2: Code is Cheap, Don't Devalue Yourself](015-code-is-cheap.md). Your value isn't in pushing the button, it's in knowing which damn button to push! AI can push a lot of buttons really fast, but it is your job to know which ones. + +But what happens if you **don't** do this? +You start to rack up a cognitive debt. +The more you let AI just cook without you reviewing or intervening, the less you will understand about the project. +Why does this matter? +Because if you can't reason about the mental model of your code, you will struggle to figure out where to take the project next, as Simon Willison recently wrote about on his [blog](https://simonwillison.net/2026/Feb/15/cognitive-debt/). + +It's for this reason that I _always_ review any code that AI produces. +**If I don't understand it, it doesn't get committed.** +It's my name. +We often forget that **software has consequences**. +My colleagues trust that I produce good work. +My open source communities trust that I don't provide them with buggy or worse vulnerable code. +In this quickly accelerating world of AI generated code, don't tarnish your reputation because you're being lazy. + +### Principle \#2 - Rules for Thee, Not for Me + +The boundaries and rules we give our agents are called Guardrails. +Imagine them like the bumpers in bowling that prevent you from rolling a gutter ball. +They don't guarantee a strike, but they prevent the worst case scenarios. +We have to provide guardrails to our agents as they write code to prevent them from going completely off the rail(1). +Coding agents are often unpredictable. +Sure they get better and better every day, but they sometimes go down a rabbit hole of nonsense and produce woefully inaccurate crap. +Turns out, we already have the tools necessary, and it's the things most developers loathe. +You guessed it, testing! +{ .annotate } + +1. See what I did there? + +While many developers bemoan testing, it turns out AI _loves_ structure. +Any tool the agent can use to validate its goal enhances the capabilities of the agent and lowers the likelihood of failure. +So I make my LLM do **Test Driven Development**. +I do(1). +Have AI write the tests first, _then_ write the implementation. +This works _remarkably_ well as it causes the agent to predict failure cases and "think" more about the different code paths. +My success rate when I switched to doing this doubled. +It seemed like I couldn't miss when writing code. +Adding new features was simple because if the LLM rewrote something it shouldn't, the breakage was immediately apparent. +**AND** my code was well tested and maintained. +{ .annotate } + +1. You can see it in my [global `CLAUDE.md` file](https://github.com/MasonEgger/homedir/blob/main/.claude/CLAUDE.md?plain=1#L13). + +Want to take it a step further? +Check for coverage. +Have the LLM aim for 100% test coverage of your code. +You do have to keep an eye on this though, because sometimes AI likes to take initiative. +And by that it will test **everything** when not everything needs to be tested. +Like checking to see if an import from the standard library can be resolved. +I've had to tweak my sessions to have AI only test the _logic_ of my application and not if a library can be imported. +So while it can be a little excessive, I'd rather have it and not need it than need it and not have it. + +Still not satisfied? +Add some linters! +Mandate proper formatting! +Are you writing in Python? +Use type hints! +Y'all know Python is my favorite language. +I love the freedom and flexibility it gives me, but that comes with a cost. +One of those costs is Python's typing. +I think this function that I wrote takes a string, but the AI came through on a pass and messed it up, and now expects a 1998 Toyota Corolla. +So use a type checker to make sure that what you expect is what is _actually_ happening. + +So lint the fuck out of your project. +What's the worst that can happen? +You waste a few seconds? +Seems like a fair trade to me. + +### Principle \#3 - ~~Cattle~~ Context, not Pets + +Next let's talk about context management. +How AI manages context is one of the primary discussion points around improving AI performance and the tooling gets better every day. +Mishandling of context leads to the "dreaded context rot"(1), where the performance of AI degrades the longer you interact within a certain session. +Essentially, the longer you chat with an AI, the worse the performance gets, so we have to develop strategies for handling this. +{ .annotate } + +1. If this is not the name of the company death metal band from Anthropic I'm going to be sad. + +Now the way I handle context is similar to an SRE adage "Cattle, not Pets". +This practice dictates building of systems that can be easily replaced instead of babying a dedicated server. +So you treat the server or container like livestock for slaughter, and if it goes down you kill it and start a new one. +My context managing philosophy is the same. + +I use one session per task. +I review the code, and ensure functionality was achieved. +I update relevant context files like the local configuration files(1). +I create a summary of the session and store it in the repo. +I commit the code to GitHub. +Then I use `/clear` to clear the entire context window, and start with the next task. +{ .annotate } + +1. For example, a project level `CLAUDE.md`. + +Every task is a new beginning. +A new chance to get it right or fuck it all up. +And whether it's successful or not will depend if I properly maintained the history and roadmap **external to the agent**. +This is the true crux of it. +While different tools have gotten a **lot** better at maintaining context, it wasn't always that way. +And regressions can happen. +Like most backend engineers, I reserve the right to fire my tools at any point. +While I'm loving Claude Code now, that doesn't mean I wont eventually try out Codex. +If my history is locked in a tool, I'm locked in as well. + +So I don't baby my context window. +I just nuke it after every task and start over. +My context window is the cattle(1), not a pet. +This accomplishes two things. +It maintains that minty freshness of the models at the beginning of a session we all love so much, and it requires me to be _very deliberate_ about how I manage context in my projects. +This, in-turn, leads to better performance _regardless_ if the compaction gets better. +I'm no longer dependent on the tool or the model. +I control the context window. +{ .annotate } + +1. Should be cow, cattle is plural. But I had to make that metaphor work. + +### Principle \#4 - Prompts are Code, and Should Be Documented as Such + +No surprise, if you're familiar with my work, that I think shit should be documented and documented well. +I chose to die on this hill years ago. +I have my burial plot picked out(1). +{ .annotate } + +1. It's nice. Under an oak tree. And my headstone will read "Use the oxford comma you fools". + +Let's dive a little deeper into what a prompt is. +Prompts are text you provide to the AI to achieve a task. +They have inputs, outputs, and side effects. +They can be buggy, inefficient, or elegant. +A bad prompt produces slop, while a good prompt produces working, maintainable code. +Sound familiar? +That's because prompts **are the code now.** +It's the new abstraction layer we're all learning to speak. +Good prompts should be versioned, reviewed, and iterated on just like everything else. +Why do you think I like my custom commands so much? +When I tweak a Command and it improves, I update it and commit it. + +??? abstract "Example Session Summary from One of My Projects" + + ```md + # Session Summary: YouTube Embed & Toolchain Improvements + + **Date:** 2026-02-22 + **Duration:** ~12 minutes + **Conversation Turns:** 6 (user messages) + **Model:** Claude Opus 4.6 + **Total Cost:** ~$3.50 (estimated) + + ## Key Actions + + ### 1. Step 6: YouTube Embed (Completed) + - **RED**: Created `tests/test_youtube.py` with 10 tests across 3 classes: + - `TestYouTubeBasic` (2 tests): iframe attributes, default 16/9 aspect ratio + - `TestYouTubeDimensions` (5 tests): custom height+width, height-only, aspect ratio for default/square/custom dims + - `TestYouTubeEdgeCases` (3 tests): not matched in paragraph, not matched in fence, URL encoding + - All 10 tests confirmed failing (RED validated) + - **GREEN**: Created two new source files: + - `src/do_markdown/_util.py`: `reduce_fraction()` using `math.gcd` + - `src/do_markdown/youtube.py`: `YouTubePreprocessor` (priority 20) + `YouTubeExtension` + - All 10 tests passed on first implementation — zero debugging + - Fixed one ruff lint issue (unused `pytest` import) + + ### 2. Coverage Analysis & Gap Fix + - User asked about test coverage — ran `pytest-cov` (initially as ephemeral dep) + - **Result**: 99% coverage, 3 missing lines in `fence.py:111-113` (non-fence line path in preprocessor) + - Added `test_text_surrounding_fence_preserved` to `TestNoDirectives` class + - **Result**: 100% coverage across all 240 statements, 0 missing + + ### 3. Toolchain Restructuring + - Added `pytest-cov>=7.0` to dev dependencies in `pyproject.toml` + - Restructured justfile commands: + - `just test` — pytest with `--cov=do_markdown --cov-report=term-missing` + - `just lint` — ruff check + ruff format --check + - `just typecheck` — mypy --strict + - `just check` — composes `test lint typecheck` as just dependencies (not reimplemented) + - User corrected initial approach where `just check` manually listed all commands — pointed out it should just compose the other targets + - Updated `CLAUDE.md` and `MEMORY.md` to reflect new command structure + + ## Main Prompts & Commands + + | # | User Prompt | Action Taken | + |---|------------|--------------| + | 1 | `/app-dev:execute-plan` | Read context, implemented Step 6 (YouTube embed) via TDD | + | 2 | `/meta:session-summary` | Created initial session summary | + | 3 | `/git:commit-msg` | Wrote commit message to commit-msg.md | + | 4 | "What is the test coverage?" | Ran pytest-cov, identified 3 uncovered lines in fence.py | + | 5 | "Add coverage for the test case" | Added test, achieved 100% coverage | + | 6 | "Add coverage to dev packages..." | Added pytest-cov dep, restructured justfile, updated CLAUDE.md | + | 7 | User correction: "just check should just run test lint typecheck" | Simplified justfile to use just dependency composition | + | 8 | `/meta:session-summary` | Created this session summary | + + ## Efficiency Insights + + - **Excellent:** YouTube embed implemented in one pass — 10/10 tests passed on first GREEN implementation + - **Excellent:** Coverage gap identified and fixed with a single targeted test + - **Good:** Initial justfile restructuring was over-engineered (duplicated commands in `check`). User caught this and the fix was clean — `check: test lint typecheck` using just's dependency system + - **Good:** Also split `lint` to include both ruff check and format check (previously these were separate in the old `check` command) + + ## Process Improvements + + 1. **Use just dependency composition**: When creating aggregate commands, use `target: dep1 dep2 dep3` syntax instead of repeating the underlying commands. This keeps things DRY and ensures the aggregate always matches the individual commands. + 2. **Add coverage from the start**: pytest-cov should have been in the initial scaffolding (Step 1). Having coverage visibility earlier would have caught the fence.py gap sooner. + 3. **Coverage as part of `just test`**: By embedding `--cov` flags in the default test command, coverage is always visible without extra effort. + + ## Current Project State + + - **Steps 1-6:** Complete + - **Next:** Step 7 — CodePen Embed + - **Files created this session:** + - `src/do_markdown/_util.py` (reduce_fraction utility) + - `src/do_markdown/youtube.py` (YouTubePreprocessor + YouTubeExtension) + - `tests/test_youtube.py` (10 tests across 3 classes) + - `.ai-sessions/session-20260222-1113-youtube-embed.md` (mid-session summary) + - **Files modified this session:** + - `pyproject.toml` (added pytest-cov dep) + - `justfile` (restructured all commands, added coverage, composed check) + - `CLAUDE.md` (updated command documentation) + - `tests/test_fence.py` (added 1 coverage test — 39 total fence tests) + - `plan.md` (Step 6 → Done) + - `todo.md` (items 6.1–6.6 checked) + - **Full verification (`just check`):** All passing — 60 tests, 100% coverage, clean lint, clean types + + ## Observations + + - The YouTube extension is the simplest extension so far — no postprocessor needed, just line-by-line replacement in a preprocessor. This validates the architecture decision to keep embeds as simple preprocessors. + - 100% statement coverage across all 240 statements. The only gap was a non-fence-line path that was trivially covered by adding surrounding text to an existing test. + - The justfile restructuring is a nice quality-of-life improvement. Individual commands (`test`, `lint`, `typecheck`) are independently useful, and `check` composes them cleanly. + ``` + +So documenting prompts, I believe, is just as important as documenting the code. +Why? +Because documenting your code is something you do for the user. +Historically, however, we've been **REALLY BAD** about documenting stuff for the implementer. +And documenting your prompts does this. +It captures the history of the project. +How often do you look at a legacy codebase and just go "WHY?!?!" + +![Sheldon cooper reading a paper and yelling WHY gif](img/016-ai-principles/why.gif) + +Well now, if the implementation is being done via agents, we have a much better way of at least stitching together the conversations that were being had and why things are the way they are. +But this does beg the question, how _does_ one document prompts? + +Every tool has some way of exporting sessions, but I don't think that's enough. +I take it one step further and actually have a template for this that I have AI use to create a similar report after every session. +This template contains a recap of key actions, the main prompts and commands, cost, efficiency insights, possible process improvements, and any other interesting observations or highlights. +I then store these sessions in `.ai-sessions/` in the code repository and commit them. +Now I have a history. +I can use AI to look over them and generate some lessons learned and update its memory and context. + +## Anti-patterns That Will Slow You Down + +Ok, so I've listed all the things you _should_ do, but what about some things you **shouldn't** do? +These are the things that I am bored with, tired of, and pissed at. + +### Anti-pattern \#1 - One Shots + +This bugs the hell out of me. +People try giving an LLM the prompt "build facebok"(1) and then getting upset it didn't get it right on the first try. +Really? +Is that how _you_ develop? +With no spec, no plan, and you get 20 minutes typing as fast as you can? +No you don't. +So stop expecting AI to do the same. +Yes, it can get _very_ far without aid. +But in my opinion this isn't a good thing. +The further ahead it gets of you, the less you understand about the project. +So ya, stop with the one shots. +It's dumb. +{ .annotate } + +1. Intentional misspelling to demonstrate the level of ignorance it takes to type this into an LLM. + +### Anti-pattern \#2 - Model of the Month + +I chose Claude a while back because I appreciate Anthropic's mission statement. +I never really gave other models a chance, and I don't really care to. +Why? +Because the differences between the flagship models of the large AI companies are never _really_ that big. +And if there is a gulf, it won't be there long. +I view this as a Formula 1 race. +Everyone's going really fast, all going for first, and who's in lead changes constantly. +Today Anthropic is in the lead by an inch. +Tomorrow it'll be OpenAI. +Then Google. +Then Anthropic pulls ahead again. +And to spend what limited capacity my brain has to focus on this is pointless. +If Anthropic isn't the best in the world I'm fine with that. +I'll wait a few weeks until it is again. + +### Anti-pattern \#3 - Feature of the Month + +This is a big one. +I shout this from the rooftops in the communities I'm in. +These AI companies are using AI to build AI. +That means they are shipping features at a velocity we've never seen before. +Honestly, I think this leads to "feature fatigue". +This is where you just get exhausted from constantly having to try to keep up with what's going on ON TOP OF your other responsibilities. +This happens to me all the time. +I see a new feature and I'm like, I can't wait to try that when I have some free time in a few days! +And by the time those few days pass, there's a new feature. +So I try to keep up. +But then what if I take a vacation and am gone for a few weeks? +Shit there's like 8 new features when I get back! +This actually happened to me, and it made kinda step back from AI for a while. +I only stepped forward again when I built myself the following framework. + +1. I will focus on MVW - Minimum Viable Workflow +2. I will only use new tools when I actually have a _need_ for them +3. I will ignore most of the announcements, or at least spend no more than 20 minutes on them until I'm ready for them + +Are there a shit ton of _awesome_ features I want to try right now? +Ya! +Am I going to? +Nope! +Not until I need them. +Maybe I'll set aside some time to catch up eventually. +But product adoption happens on my timeline, not Anthropic's. + +Do I feel left out on this? +Honestly, no. +Because for all these features, I am still producing at the rate I want, and I never see anyone gain any real serious ground by adopting them. +I have a friend who just prompts away in a CLI interface, and his output and quality are vastly superior to mine. +At the end of the day, a Stradivarius in the hands of a beginner is just a piece of wood. + +### Anti-pattern \#4 - Worrying About What Others Are Doing + +If you spend any amount of time on a social media platform where developers congregate you'll see a _metric fuck tonne_ of posts about how everyone is using AI. +This person used it to port their entire code base JS to Rust! +Another person used it to build a side business that's now generating passive income! +This person over here learned the Elder Prompt and has ascended into the singularity! +And if you refresh the page there's **100,000,000** more people saying the exact same thing a slightly different way! + +It's exhausting. +And it's easy to let yourself feel like you're behind the 8 ball on this one. +Trust me, you're not. +More than half those people online are full of shit. + +``` +Person 1: "I spent all weekend optimizing my Claude Code setup!" + +Person 2: "Oh cool! What did you build?" + +Person 1: "I now have a custom command that reads all my commands and optimizes them and writes them out as a Skill! + +Person 2: "That's awesome! How will that help you build?" + +Person 1: "Well next I'm going to optimize..." +``` + +And the cycle just continues(1). +So my best advice is to not let yourself get distracted by everyone else. +The reality of life is there will always be someone better than you. +As soon as I feel good about my AI setup and output, I read a blog that makes me feel like a beginner again. +And that's a **good thing**! +Because there is always something new to learn. +{ .annotate } + +1. And if you're looking at my blogs going "Hey wait aren't you doing the same thing?" No. Totally not. Hush. + +So don't let FOMO, or Fear of Missing Out, distract you on your journey. +Don't let others who are further on their journey discourage you. +It's a marathon, not a sprint. +And the race is just getting started. + +## A Method to My Madness + +You may be wondering(1) why I'm focusing on things like this and not just jumping right into the implementation. +Developers are notorious for their "just show me the code" mentality. +And ya, I could have done that. +But then you might miss the ramifications of what is happening. +AI isn't another library. +It isn't a new framework or programming language or whatever the hell else you want to compare it to in our industry. +It's a **fundamental shift** in how we work. +{ .annotate } + +1. Especially if you've read this entire series. + +A standard Computer Science curriculum has at least one course on Data Structures and Algorithms. +In this course you learn how various algorithms are built, the core data structures in programming languages, performance analysis (Big O) and more. +However, in your career it is _highly unlikely_ you'll ever implement a merge sort by hand. +So why do we take the time to learn this? + +Because we want to gain an understanding of how the system works. +Through this understanding, we learn how to properly implement solid solutions. +Sure you don't _need_ to learn this content. +There are successful developers out there right now who never did. +But those developers are likely missing(1) a key part of the mental model. +This is the key differentiator between a craft and a discipline(2). +The carpenter knows how to build the house, but the architect understands _why_ it has to be his way and dismissed other solutions that weren't appropriate. +{ .annotate } + +1. Unless they learned about it after, either formally or through experience. +2. Check out [Blog 1: We're Witnessing the Evolution of Software Engineering](014-software-engineering-evolution.md) for more details. + +I fear that those who say "just show me the code" with regards to using AI in this era are setting themselves up for failure down the road. +It's not just enough to know the magic incantation to chant to the LLM. +You have to understand why that incantation needs to be said. +Otherwise who knows what Eldritch Terror you'll unleash. + + + +_[Video link](https://www.youtube.com/watch?v=qwTop2qs1tE)_ + +--- + +_Ready to see these principles in action? Stay tuned for the next part of this series, How I Actually Use the Damn Thing._ + +!!! abstract "Part 3 of 5 of my `Brain Dump Ramblings on AI` blog series" + + Check out the other parts of this series: + + * Part 1 - **[We're Witnessing the Evolution of Software Engineering](014-software-engineering-evolution.md)** discusses the historical context and ongoing evolution of software engineering up to the advent of AI. + * Part 2 - **[Code is Cheap, Don't Devalue Yourself](015-code-is-cheap.md)** discusses AI and it's impact on the software engineering discipline. + * Part 4 - **How I Actually Use the Damn Thing** - My journey with Claude Code and my tips and tricks for getting started. *Coming Soon* + * Part 5 - **Skills, Plugins, and MCP Oh My!** - A deep dive into Claude Code's customization features. *Coming Soon* + + + diff --git a/docs/blog/posts/img/016-ai-principles/why.gif b/docs/blog/posts/img/016-ai-principles/why.gif new file mode 100644 index 0000000..61ad4f9 Binary files /dev/null and b/docs/blog/posts/img/016-ai-principles/why.gif differ diff --git a/docs/blog/posts/img/017-claude-code/toolbelt.gif b/docs/blog/posts/img/017-claude-code/toolbelt.gif new file mode 100644 index 0000000..2bf0e5b Binary files /dev/null and b/docs/blog/posts/img/017-claude-code/toolbelt.gif differ diff --git a/docs/extras/index.md b/docs/extras/index.md index 77cc39d..8427061 100644 --- a/docs/extras/index.md +++ b/docs/extras/index.md @@ -16,6 +16,7 @@ If you find it useful too then that's alright too. lol :stuck_out_tongue_closed_ * [*Maker's Schedule, Manager's Schedule* - Paul Graham](http://www.paulgraham.com/makersschedule.html) * [*Always be quitting* - Julio Merino](https://jmmv.dev/2021/04/always-be-quitting.html) * [*How to help a student get unstuck*](https://offbyone.us/posts/how-to-help-a-student-get-unstuck/) +* [*My AI Adoption Journey* - Mitchell Hashimoto](https://mitchellh.com/writing/my-ai-adoption-journey) ### Books diff --git a/docs/index.md b/docs/index.md index aa68e5b..6139627 100644 --- a/docs/index.md +++ b/docs/index.md @@ -35,7 +35,10 @@ My recent **Brain Dump Ramblings on AI** series
    diff --git a/docs/tutorials/posts/004-claude-code-quickstart.md b/docs/tutorials/posts/004-claude-code-quickstart.md new file mode 100644 index 0000000..190032a --- /dev/null +++ b/docs/tutorials/posts/004-claude-code-quickstart.md @@ -0,0 +1,184 @@ +--- +title: How To Use Claude Code with My BPE Workflow [Quickstart] +description: Get productive with Claude Code using my Brainstorm-Plan-Execute loop +date: 2026-02-17 +categories: + - AI + - Productivity + - Software Engineering +authors: + - masonegger +--- + +This quickstart guide gets you up and running with my personal Brainstorm-Plan-Execute (BPE) workflow for Claude Code. +You'll install custom commands that structure your AI-assisted development into repeatable, reviewable steps. + + + +## Introduction + +The BPE workflow breaks down AI-assisted development into three phases: **Brainstorm** your idea into a specification, **Plan** the implementation with generated prompts, and **Execute** each step with manual review. +This approach produces maintainable code you actually understand. + +For the full context behind this workflow, including Core Principles and detailed explanations, see [How I Actually Use the Damn Thing](/blog/posts/016-claude-code/). + +## Prerequisites + +Before starting, ensure you have: + +- [Claude Code](https://code.claude.com/docs/en/overview) installed via the native installer and either an Anthropic API key or a Claude Subscription +- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) installed +- Git installed +- A code project to work on + +## Step 1 — Installing the BPE Workflow Commands + + +The BPE commands live in a `homedir` repository that uses Ansible for installation. Clone the repository and run the playbook: + +```bash +cd ~ +git clone https://github.com/MasonEgger/homedir.git +cd homedir +ansible-playbook ansible/setup.yml --tags claude +``` + +This installs: + +- `~/.claude/CLAUDE.md` — Global configuration with development principles +- `~/.claude/commands/` — Custom commands including the BPE workflow +- `~/.claude/skills/` — Conditional context loading for languages like Python + +## Step 2 — Initializing Your Project + +Navigate to your project directory and start Claude Code: + +```bash +cd /path/to/your/project +claude +``` + +Before diving into work, set the output style to `Explanatory` mode. This makes CC explain what it's doing as it works, helping you learn and catch mistakes early: + +``` +/output-style +``` + +Select `Explanatory` from the menu. If you want even more detail (pair-programming style), choose `Learning` instead. + +Now run `/init` to create your project context: + +``` +/init +``` + +This scans your project and creates a `CLAUDE.md` file with project-specific context. Review the generated file and commit it: + +```bash +git add CLAUDE.md +git commit -m "Add project CLAUDE.md for AI context" +``` + +???+ tip "Prefer vim keybindings?" + + Run `/vim` to enable vim-style navigation and editing in Claude Code. + +## Step 3 — Brainstorming Your Feature + +Start a brainstorming session by running the command with your idea: + +``` +/app-dev:brainstorm Build a CLI tool that converts PDF files to Markdown +``` + +Claude Code will ask you questions one at a time to refine your idea. Answer each question thoughtfully. When finished, it creates `spec.md` with your specification. + +**Review `spec.md` manually.** Fix any errors or misunderstandings before proceeding. This file is the foundation for everything that follows. + +### Loading External Documentation + +If your project uses a specific library or framework, you can load its documentation into context without copying it into your project. Clone the docs repo alongside your project: + +```bash +cd .. +git clone https://github.com/some-library/docs.git some-library-docs +cd your-project +``` + +Then inside Claude Code: + +``` +/add-dir ../some-library-docs +``` + +CC can now reference those docs when answering questions or writing code that uses that library. + +## Step 4 — Creating a Plan + +Clear your context and generate the implementation plan: + +``` +/clear +/app-dev:plan +``` + +This reads `spec.md` and creates two files: + +- `plan.md` — Step-by-step prompts for implementation, following Test-Driven Development +- `todo.md` — Checklist mirroring the plan to track progress + +**Review `plan.md` manually.** Verify the prompts make sense and follow your preferred patterns. Check that file paths are correct and test scenarios are appropriate. + +### Resuming a Session + +Need to step away? You can close your terminal at any point. When you come back, start Claude Code and run: + +``` +/resume +``` + +This restores your previous session with full context intact. + +## Step 5 — Executing the Plan + +Clear your context and start executing: + +``` +/clear +/app-dev:execute-plan +``` + +Claude Code reads `todo.md` to find the next unchecked item, loads the corresponding prompt from `plan.md`, and implements that step using TDD. + +After each step completes: + +1. Review the generated code +2. Manually run tests to verify they pass +3. Commit the changes +4. Run `/clear` to reset context +5. Run `/app-dev:execute-plan` again for the next step + +Repeat until `todo.md` is complete. + +## Conclusion + +You now have a structured workflow for AI-assisted development: + +1. **Brainstorm** creates `spec.md` from your idea +2. **Plan** generates `plan.md` and `todo.md` with implementation prompts +3. **Execute** implements one step at a time with manual review between each + +### Saving Your Session + +Before closing out, you can export the raw text of your session for archival or sharing: + +``` +/export +``` + +This saves the full conversation to a file you can reference later or share with teammates. + +For the complete picture—including Core Principles like "This is MY Code, Not AI Code" and detailed explanations of Skills, context management, and more—read the full blog post: [How I Actually Use the Damn Thing](/blog/posts/016-claude-code/). + +*[CC]: Claude Code +*[BPE]: Brainstorm, Plan, Execute