Skip to content

ShadowHound Development Log

Purpose: Lightweight timeline of daily development activities
Audience: Future developers, AI agents, project stakeholders
Update Frequency: After completing work (simple entry with link to experiment doc if applicable)

For Agents: - Simple work: Add lightweight entry here with key results and commits - Experimental work: Create experiment doc in experiments/, link from here - See: experiments/README.md for when to use experiment docs vs. devlog

2025-10-20 (Sunday)

Late Evening: Tower Fresh Install + Complete Stack Validation (21:00-23:30)

Type: Infrastructure Status: ✅ Complete

Fresh Tower installation after deleting .go2_stack_state markers. Successfully deployed complete simulation + data lake stack.

Key Results: - ✅ Simulation working: Go2 in Isaac Sim with LiDAR + camera streaming - ✅ Keyboard control: Teleoperation functional - ✅ ROS2 topics: All topics visible and streaming - ✅ RViz2 visualization: LiDAR point cloud + camera feed working - ✅ MinIO: Object storage running on dual drives - ✅ MLflow: Experiment tracking operational - ✅ Data persistence: 5.4TB total storage (1.8TB + 3.6TB platters)

Configuration: - Platter drives mounted: - sda1 (1.8TB): UUID=a28b5c28-f459-41a6-9d25-b0a50c7c9d8a → /mnt/data1 - sdb1 (3.6TB): UUID=c7951339-6757-43ec-ac78-0a0fd6ed9d5f → /mnt/data2 - Added to /etc/fstab for auto-mount on boot - Base data dir: /mnt/data1 - MinIO drives: Both /mnt/data1 and /mnt/data2 for distributed storage

Issues Resolved: 1. LiDAR Config Workaround (known limitation): - Script tries to copy LiDAR configs during workspace build - Destination directory created only after Isaac Sim first run - Workaround: Manually copy files after Isaac Sim runs once: bash cp ~/workspace/go2_omniverse/Isaac_sim/Unitree/Unitree_L1*.json \ ~/miniconda3/envs/env_isaaclab/lib/python3.10/site-packages/omni/data/Kit/Isaac-Sim/4.5/exts/3/isaacsim.sensors.rtx*/data/lidar_configs/ - Root cause: pip install creates base structure, runtime directories populated on first launch

  1. MinIO Volume Mapping (configuration issue):
  2. Docker compose had volumes swapped (/mnt/data2:/data1, /mnt/data1:/data2)
  3. Caused by drive selection order during installation
  4. Fixed by correcting volume mappings in docker-compose.yml
  5. MinIO and MLflow now operational

Next Phase: - Explore laptop stack running against Go2 robot in simulation - Design simulation orchestration (startup automation) - Work to be done in new feature branch

Commits: TBD (pending)

Evening: Repository Cleanup After Isaac Sim Success (19:00-20:00)

Type: Cleanup + Refactoring Status: ✅ Complete

Archived 14 obsolete debugging scripts and 8 experimental/completed documentation files after successful Tower Isaac Sim + Isaac Lab deployment. Cleaned repository to remove troubleshooting artifacts from multi-day debugging session.

Key Results: - Scripts archived (14): tower_setup_go2_sim.sh superseded; debugging tools (diagnose, fix, test); version management scripts (rollback, upgrade, downgrade) - Docs archived (8): Tower troubleshooting guides (3); Docker containerization experiments (2, not adopted); legacy Codex notes (2); completed vcs→submodule conversion guide (1) - Kept active: sim_and_data_lake_setup.sh (complete working solution), tower_update_nvidia_driver.sh (referenced), laptop_isaac_sim_development.md (distributed dev workflow) - Repository cleaner: Only production scripts and active documentation remain

Archived Scripts: - tower_setup_go2_sim.sh → scripts/legacy/ (replaced by sim_and_data_lake_setup.sh) - tower_diagnose_isaac_freeze.sh, tower_diagnostic_isaaclab.sh, tower_quick_import_test.sh - tower_fix_lidar_config.sh (manual fix, now automated) - tower_rollback_.sh, tower_check_.sh, tower_upgrade_.sh, tower_downgrade_.sh - tower_test_sim_after_upgrade.sh, tower_try_v2.1.1.sh - tower_complete_uninstall_isaac.sh

Archived Docs: - TOWER_UPGRADE_QUICKSTART.md, tower_isaaclab_upgrade_guide.md, tower_version_compatibility.md - isaac_sim_containerized_setup.md, isaac_sim_docker_scripts_comparison.md (Docker experiments) - codex_24_04_plan.md, codex_environment_strategy.md (legacy Codex notes) - laptop_sync_after_conversion.md (vcs→submodule conversion complete)

Commits: 97f56fe — chore: archive obsolete Isaac Sim debugging scripts and docs

2025-10-19 (Saturday)

All Day: Tower Isaac Sim + Isaac Lab Complete Deployment (08:00-23:00)

Type: Infrastructure + Debugging Status: ✅ Complete
Experiment Doc: experiments/tower_isaac_sim_deployment_oct19_2025.md

Successfully deployed complete Isaac Sim 4.5.0 + Isaac Lab v2.1.0 + go2_omniverse simulation stack on Tower with full ROS2 integration. Resolved 9 critical issues through systematic debugging spanning 15+ hours and 48+ commits.

Key Results: - ✅ Full simulation working: LiDAR and camera streaming to RViz2 - ✅ Isaac Sim 4.5.0: pip install to conda env (env_isaaclab) - ✅ Isaac Lab v2.1.0: Source install, April 24 2025 commit (validated compatible) - ✅ NVIDIA Driver 580.95.05: Validated and working - ✅ ROS2 Humble: Complete workspace builds with system Python separation - ✅ go2_omniverse: added_copter branch fully functional

9 Issues Resolved: 1. Driver check early return (removed marker file bypass) 2. ROS_DISTRO undefined (added to .bashrc) 3. 404 errors for ROS2 packages (always update apt cache) 4. Conda/Python conflicts (force deactivation before builds) 5. Missing lark-parser (install hyphenated version to system Python) 6. Symlink conflicts (clean build directories) 7. Missing ros-humble-tf-transformations (apt-get install) 8. Missing transforms3d (conda env install) 9. LiDAR config files missing (copy to Isaac Sim 4.5 directory, not Isaac Lab)

Script Enhanced: scripts/sim_and_data_lake_setup.sh - System Python dependencies (empy==3.3.4, lark-parser) - Conda environment dependencies (transforms3d, etc) - ROS2 system packages (ros-humble-tf-transformations) - Environment variable management (ROS_DISTRO=humble) - Conda deactivation before builds (prevents conflicts) - Build directory cleaning (removes stale symlinks) - Correct LiDAR config paths (Isaac Sim 4.5, not Isaac Lab)

Validation: - User confirmed: "the sim is running, no errors and we have lidar and camera in rviz2!!!!!" - LiDAR configs in correct location: ~/.local/share/ov/pkg/isaac-sim-4.5.0/exts/omni.isaac.sensor/data/lidar_configs/ - Complete setup script validated against working Tower configuration

Architecture Validated: - System Python (/usr/bin/python3) for ROS2 builds - Conda Python (env_isaaclab) for Isaac Sim execution - Separation critical for avoiding libpython conflicts

Next Phase: Distributed testing (laptop connecting to Tower Isaac Sim)

Commits: 48+ commits including 6085b24, 7793d78, f7ca46a, 196338c, 6d5fb2f, b0d2618

2025-10-18 (Friday)

Morning: Tower Setup Script Production Hardening (06:00-09:00)

Type: Infrastructure + Security Status: ✅ Complete

Comprehensive production hardening of Tower simulation and data lake setup script. Fixed 12 critical/high-priority issues identified in systematic review. Script increased from 1483 to 1618 lines (+135 lines of safety code).

Key Results: - State Management: Fixed reconfiguration commands (write data_dir.txt, minio_dir.txt) - Docker Compose Validation: Enhanced detection with functionality testing - Credential Validation: Added checks after sourcing .env, prevents corruption - Automatic Rollback: Credential rotation restores old credentials on failure - Health Checks: Enhanced with container status monitoring (detects crashes) - Docker Group: Added membership validation with clear error messages - Disk Space: Enhanced validation for both root and data directory - Drive Validation: Check writable + space before accepting MinIO drives - Systemd Testing: Test service startup after creation - Install Detection: Warn on existing installation with confirmation prompt - Progress Indicators: Added feedback for 15-30 minute Isaac Sim install - Service Feedback: Counter in health check wait loops

Documentation Created: - SCRIPT_HARDENING_REVIEW.md (18 issues identified, fixes documented) - SCRIPT_TEST_PLAN.md (50+ tests, 8 test suites, validation procedures) - SCRIPT_HARDENING_SUMMARY.md (complete changelog with code examples) - TOWER_SETUP_QUICK_REF.md (user-facing commands and troubleshooting) - tower_sim_datalake_setup.md (complete Tower setup guide) - tower_security_credentials.md (credential generation, rotation, transfer) - tower_thor_spark_integration_guide.md (step-by-step integration) - tower_lerobot_soarm101_setup.md (optional robotic arm extension, 850+ lines) - combined_go2_soarm_workflows.md (optional integration patterns, 600+ lines)

Script Features: - Commands: install, test, doctor, uninstall, reconfigure-{drives,network,credentials} - Automatic credential generation (OpenSSL random, chmod 600) - Systemd integration (auto-start on boot) - Firewall configuration (local networks only) - Network documentation generation - MinIO + MLflow + PostgreSQL containerized stack

Validation: - Syntax check: bash -n passed - Script: 1618 lines (production-ready) - Ready for manual testing on Ubuntu 22.04 VM

Commits: ca69b45 — feat(tower): production-ready setup script with comprehensive hardening

2025-10-15 (Wednesday)

Morning: Persistent Intelligence — Research Docs & Alignment (09:00-11:30)

Type: Documentation + Architecture Research Status: ✅ Complete

Authored and linked a focused set of research docs to clarify the Day-One system context, Ops vs Avatar separation, LoRA/adapter roles, and how personality overlays vs. evolution are governed. Verified dev branch alignment and committed updates.

Key Results: - Day-One mission context documented ("check oven" flow, offload to avatar, background learning) - Personality decoupling patterns (Ops vs Research modes, overlays vs checkpointed evolution) - LoRA/adapter decision guide and serving topologies (local-only for memory write/recall; cloud via prompting) - Concrete Ops vs Avatar examples (memory persistence, persona overlays, promotion workflow) - Alignment review: reconciled prior plans with current model; locked short-term decisions, flagged follow-ups

Docs Added: - research: lora_adapters_persistent_intelligence.md - research: persistent_intelligence_day_one_system_context.md - research: personality_and_mission_execution.md - research: ops_vs_avatar_concrete_examples.md - research: alignment_review_persistent_intelligence_oct15.md

Commits: 4148f28 — docs(research): persistent intelligence exploration — system context, personality decoupling, ops vs avatar examples, LoRA architecture, alignment review

2025-10-14 (Tuesday)

Late Evening: PR #30 Review & Merge - Wiki Sync Fix (07:30-08:00)

Type: PR Review Status: ✅ Complete Impact: Wiki now displays cleanly without YAML metadata and all links work correctly

Problem Solved: - Wiki pages showed raw YAML front-matter at top - Links pointed to markdown files instead of wiki pages - Navigation broken in wiki interface

Solution Implemented (by @copilot-swe-agent): - ✅ YAML stripping: Regex pattern removes --- blocks from file start - ✅ Wiki-style links: Converts paths to Title-Case-With-Hyphens format - ✅ Comprehensive tests: 7/7 tests passing (test_link_convert.py) - ✅ Documentation updated: Examples and troubleshooting in wiki_sync.md

Conversions Validated: - [text](docs/path/page.md) → [text](Page) ✓ - [\[config_file]] → [config_file](Config-File) ✓ - [\[path/to/page|Label]] → [Label](Page) ✓ - External links, anchors, images preserved ✓

Files Changed: - tools/link_convert.py - Added YAML stripping + wiki slugification - tools/test_link_convert.py - New comprehensive test suite (256 LOC) - docs/deployment/wiki_sync.md - Updated with examples

Validation: 209 markdown files processed successfully, all checks passing

Commits: PR #30 (squashed), closes Issue #29

Late Evening: README Correction & Root Directory Cleanup (07:00-07:30)

Type: Documentation Fix + Repository Organization Status: ✅ Complete Impact: README now accurately reflects actual accomplishments, root directory cleaned for main merge

Problem Discovered: - Previous README based on incorrect status_analysis_2025_10.md - Status analysis claimed "no implementation" when ~2,100 LOC exists - Analysis contradicted comprehensive project_history_oct_2025.md - Root directory cluttered with test scripts and model files

Corrections Made: - ✅ Archived incorrect status analysis to docs/legacy/status_analysis_2025_10_incorrect.md - ✅ Rewrote README emphasizing embodied AI platform (not just household assistant) - ✅ Fact-checked MVP roadmap (accurate - no changes needed) - ✅ Organized root directory: - LAPTOP_SYNC_COMMANDS.sh → scripts/ - Test scripts → test_scripts/ - yolo11n.pt removed, models/ added to .gitignore

README Now Correctly States: - Primary Goal: Embodied AI platform for transformer exploration (LLM, VLM, VLA) - Household missions are test scenarios, not sole purpose - Mission agent implemented (~2,100 LOC) - Custom FastAPI web UI (479 LOC built from scratch) - Dual LLM backends validated on hardware (OpenAI + vLLM) - 389 commits in 10 days (Oct 3-13) - SLAM + Nav2 tested on physical Go2 - Known constraints documented (WebRTC API, MockRobot, Thor GPU)

Note: First commit (e4969fb) had file corruption, reset to 091e2aa and redone cleanly.

Commits: 711dfde (clean version with all corrections)

Late Evening: Dev Branch Preparation for Main Merge (06:45-07:00)

Type: Infrastructure + Documentation Status: ⚠️ Superseded by correction above Impact: Main branch protected, but README needed correction

Activities: - Enabled branch protection on main branch (requires PR, status checks, no force push) - Updated root README (but based on incorrect status analysis) - Simplified and modernized content structure - Added MVP roadmap focus and goals - Updated documentation links (Wiki + Pages now working)

Branch Protection Settings (still valid): - ✅ Requires pull request for merge - ✅ Requires "check-links" status check to pass - ✅ No force pushes allowed - ✅ No deletions allowed - ✅ Admins not enforced (allows emergency fixes)

Next Steps: - Wait for Issue #29 PR (wiki conversion improvements) - Review and merge Issue #29 when ready - Merge dev → main (after Issue #29) - Development directory cleanup (tomorrow)

Commits: 091e2aa (initial README), e8c9509 (devlog)

Evening: PR #28 Review & Merge - Wiki Sync for Dev Branch (06:30-06:45)

Type: PR Review PR: #28 Status: ✅ Complete Impact: Dev branch now auto-syncs docs to GitHub Wiki on every push

Activities: - Reviewed PR #28 from cloud agent (Issue #26 - Wiki sync for dev branch) - Verified workflow structure mirrors existing docs.yml pattern - Validated comprehensive 227-line documentation (wiki_sync.md) - Confirmed all CI checks passing - Approved and merged via squash commit

Files Added: - .github/workflows/wiki-sync.yml - Dev branch wiki sync workflow - docs/deployment/wiki_sync.md - Complete wiki sync documentation (227 lines)

Files Updated: - AGENTS.md - Clarified CI syncs on both dev and main branches - README.md - Added wiki and GitHub Pages links - docs/deployment/deployment_hub.md - Added wiki sync documentation link

Key Decisions: - Architecture: main branch (MkDocs + Wiki), dev branch (Wiki only) - Saves CI time: No MkDocs build on dev branch - Fast feedback: Dev changes sync to wiki immediately

Validation: - ✅ Workflow uses existing tools (wiki_sync.py, link_convert.py) - ✅ Proper trigger (dev branch, docs/** changes only) - ✅ Authentication via GITHUB_TOKEN (standard approach) - ✅ Documentation follows ShadowHound patterns - ✅ Agent fixed wikilink validation issue during implementation

Wiki Setup: - User manually created first wiki page (required to initialize wiki git repo) - Workflow triggered and succeeded on test push - Wiki now auto-syncs on every docs/ change to dev branch - Verified at: https://github.com/danmartinez78/shadowhound/wiki

Issues Discovered: - ❌ YAML front-matter visible in wiki pages (should be stripped) - ❌ Links point to raw markdown files (should be wiki page names) - Created Issue #29 for cloud agent to fix link_convert.py

Commits: b0217cb (squash merge), 338de1c (devlog), 703c043 (wiki test), 8afe2e1 (wiki validation)

Afternoon: Experiment Documentation System Created (02:30-03:30)

Type: Documentation + Process Status: ✅ Complete

Created experiment documentation system for parallel development without merge conflicts.

Key Results: - Created docs/development/experiments/ directory structure - Created comprehensive guide: experiments/README.md (520 lines) - Created template: experiments/template_experiment.md - Created 2 example docs from historical work: - local_llm_exploration_oct10_2025.md (248 lines - 4 models tested) - dimos_integration_oct05_2025.md (274 lines - 7 experiments) - Updated agent instructions (AGENTS.md, copilot-instructions.md) - Updated devlog to lightweight timeline format

Pattern Established: - Simple work → lightweight devlog entry - Experimental work → detailed experiment doc + lightweight devlog pointer - No merge conflicts (each experiment = unique file) - Preserves experimental learning (what worked, what didn't, why)

Commits: 71f1cc4

Morning: PR #25 Review & Devlog Date Corrections (01:00-02:30)

Type: Documentation Review + Fix
PR: #25
Status: ✅ Complete
Impact: PR #25 ready to merge with complete devlog history preserved

Activities: - Reviewed PR #25 from cloud agent (Issue #23 - src/ docs consolidation) - Discovered date labeling errors across entire devlog (all dates off by one day) - Fixed dates on dev branch systematically (Oct 9-14 corrected) - User manually resolved merge conflicts in pr-25 devlog - Fixed remaining date labels on pr-25 branch (Oct 9-13 corrected) - Added missing Obsidian consolidation entry to pr-25 to preserve both Oct 13 Late Night entries - Verified both cloud agent work entries preserved (PR #24 and PR #25)

Commits: - f9c9a81 (dev) - fix(devlog): correct day-of-week for all October dates - c076a1b (pr-25) - fixed merge conflicts in devlog (user's manual work) - d46588a (pr-25) - fix(devlog): correct remaining day-of-week labels - 0cd9ee2 (pr-25) - docs(devlog): add Obsidian consolidation entry to preserve both Oct 13 Late Night entries

Key Decisions: - Preserve all cloud agent work: Both PR #24 and PR #25 entries documented under Oct 13 (Monday) - Correct date labels: Systematically fixed all dates (Oct 14=Tuesday, Oct 13=Monday, etc.) - Methodical approach: Fixed dev branch first, then handled pr-25 separately

Discoveries: - All devlog dates were labeled one day ahead (likely timezone confusion during PR creation) - Multiple rebase/retry cycles needed to learn proper conflict resolution - pr-25 devlog is more accurate (contains PR #25 work documentation)

Validation: - ✅ Both Oct 13 Late Night entries present on pr-25 (Obsidian + Source consolidation) - ✅ All dates corrected (Oct 9-14 have correct day-of-week labels) - ✅ Chronological ordering maintained - ✅ No duplicate date headers - ✅ pr-25 branch pushed to origin/copilot/consolidate-src-documentation

Notes: - PR #25 ready to merge via GitHub UI - Both cloud agent PRs (#24, #25) properly documented with correct dates - Complex session but complete devlog history preserved

Early Morning: Obsidian Config Relocation & PR #24 Review (00:00-01:00)

Type: Documentation Organization + Fix
PR: #24
Status: ✅ Complete
Impact: Fixed .obsidian tracking issue, PR #24 merged

Activities: - Reviewed PR #24 from cloud agent (Issue #22 - Obsidian docs consolidation) - Identified issue: .obsidian/ tracked at docs/.obsidian/ (bloated git tracking) - Fix applied: Moved docs/.obsidian/ → docs/tools/obsidian/.obsidian/ - Updated scripts/generate_obsidian_vault.sh to use new location - Updated agent instructions (AGENTS.md, copilot-instructions.md) - Updated obsidian tool documentation (README.md, guide.md) - Tested vault generation: ✅ 211 files converted successfully - Added PR comment explaining fix

Commits: - 04743df - fix(obsidian): move .obsidian config to tools/obsidian/

Key Decisions: - Stop tracking entire .obsidian: Moved to tools dir as "configuration template" - Clearer semantics: Config lives with tool documentation, not at docs root - Reduced git bloat: .obsidian/ no longer polluting docs/ root

Rationale: - Original approach tracked full .obsidian/ at docs root (confusing, bloated) - New approach: template lives with tool docs, gets copied during vault generation - Users can customize locally in docs_obs/.obsidian/ (gitignored) - Template ensures consistent starting point for all developers

Validation: - ✅ Script generates vault successfully - ✅ Config copied to correct location (docs_obs/.obsidian/) - ✅ All references updated - ✅ No functionality changes

Notes: - PR #24 ready to merge after this fix - Cloud agent did excellent mechanical work - This fix addresses architectural concern raised during review

2025-10-13 (Monday)

Late Night: Source Documentation Consolidation (02:36-03:00 UTC / 19:36-20:00 PDT Oct 13)

Type: Documentation + Organization
PR/Issue: #25
Status: ✅ Complete
Impact: All package documentation consolidated under docs/software/packages/ with clear structure and cross-references

Activities: - Discovered 7 markdown files in src/ packages (excluding submodules) - Created docs/software/packages/ directory structure - Moved all 3 package READMEs to docs/software/packages/{package_name}/ - Moved 3 mission agent architecture/design docs (lowercase naming convention) - Moved legacy architecture doc to docs/legacy/ - Created comprehensive docs/software/packages/README.md (242 lines) as package index - Created new src/README.md (168 lines) as quick reference with links - Updated 4 cross-references in other docs (integrations, deployment, development) - Fixed 4 broken links in moved docs (skills README references)

Commits: - bc7015f - docs(software): consolidate src/ docs to docs/software/packages/

Files Moved:

src/shadowhound_bringup/README.md → docs/software/packages/shadowhound_bringup/README.md
src/shadowhound_skills/README.md → docs/software/packages/shadowhound_skills/README.md
src/shadowhound_mission_agent/README.md → docs/software/packages/shadowhound_mission_agent/README.md
src/shadowhound_mission_agent/AGENT_ARCHITECTURE.md → docs/software/packages/shadowhound_mission_agent/agent_architecture.md
src/shadowhound_mission_agent/AGENT_DESIGN.md → docs/software/packages/shadowhound_mission_agent/agent_design.md
src/shadowhound_mission_agent/WEB_INTERFACE.md → docs/software/packages/shadowhound_mission_agent/web_interface.md
src/shadowhound_mission_agent/AGENT_ARCHITECTURE_OLD.md → docs/legacy/agent_architecture_old.md

New Structure:

docs/software/packages/
├── README.md                           # NEW: Comprehensive package index
├── shadowhound_bringup/
│   └── README.md
├── shadowhound_skills/
│   └── README.md
└── shadowhound_mission_agent/
    ├── README.md
    ├── agent_architecture.md
    ├── agent_design.md
    └── web_interface.md

src/
└── README.md                           # NEW: Quick reference with links

Decisions: - Package docs location: docs/software/packages/{package_name}/ (follows existing patterns) - Quick reference: src/README.md links to full docs (keeps src/ minimal) - Naming convention: Lowercase filenames (agent_architecture.md vs AGENT_ARCHITECTURE.md) - Legacy placement: Historical architecture doc in docs/legacy/ (not packages/) - Cross-reference updates: Only active docs updated, legacy docs preserved as-is

Validation: - ✅ No .md files in src/ except src/README.md (verified with find) - ✅ All package docs in docs/software/packages/{package_name}/ - ✅ Package index exists with comprehensive content - ✅ Quick reference in src/README.md with working links - ✅ No broken links (4 cross-references updated, 4 internal links fixed)

Notes: - Task completed as mechanical reorganization per issue requirements - No content changes to existing docs, only moves and link updates - Structure now matches three-tier pattern: software (active) vs legacy (historical) - Package documentation now centralized and discoverable

Late Night: Obsidian Documentation Consolidation (02:36-02:45 UTC)

Type: Documentation Organization
Issue: #[pending]
Status: ✅ Complete
Impact: Consolidated Obsidian-related documentation under tools structure

Activities: - Created docs/tools/ directory structure for development tools - Created docs/tools/obsidian/ directory - Moved three Obsidian documentation files: - docs/obsidian_graph_guide.md → docs/tools/obsidian/guide.md - docs/obsidian_graph_setup.md → docs/tools/obsidian/setup.md - docs/obsidian_graph_persistence.md → docs/tools/obsidian/persistence.md - Created docs/tools/obsidian/README.md explaining: - Purpose of Obsidian integration (graph view for docs) - How to use scripts/generate_obsidian_vault.sh - Where the .obsidian/ config lives (docs/.obsidian/) and why it's committed - Links to the three detailed guides - Created docs/tools/README.md with Obsidian section and future tools placeholder - Updated cross-references in: - .github/copilot-instructions.md (added link to docs/tools/obsidian/) - docs/development/MERGE_READY_docs-wiki-cleanup.md (updated file paths) - docs/tools/obsidian/persistence.md (fixed internal reference) - docs/tools/obsidian/guide.md (fixed path to .obsidian/graph.json) - Verified scripts/generate_obsidian_vault.sh still works (converted 211 files successfully) - Confirmed .obsidian/ directory remains in docs/.obsidian/ (not moved)

Commits: - bce6754 - docs(obsidian): consolidate to docs/tools/obsidian/

Key Decisions: - Tools directory pattern: Established docs/tools/ as location for development tool documentation - Keep .obsidian in place: Left docs/.obsidian/ at root of docs/ (as required) - Clear README structure: Each tool gets subdirectory with README.md + supporting docs - No functionality changes: Pure reorganization, script still works identically

Validation: - ✅ All files moved successfully via git mv - ✅ Script generates vault without errors (211 files converted) - ✅ New files appear in generated vault at correct paths - ✅ Old file locations are removed - ✅ .obsidian/ directory remains in docs/.obsidian/ - ✅ All cross-references updated - ✅ No broken links

Notes: - Part of documentation cleanup establishing clear structure - Tools documentation now has dedicated section under docs/tools/ - Sets pattern for future tool documentation (ROS2 autodoc, linting, etc.)

Late Evening: Documentation Cleanup & Organization (18:00-22:30 PDT / 01:00-05:30 UTC Oct 14)

Type: Documentation + Organization + Planning
Status: ✅ Complete
Impact: Clear three-tier documentation structure established, cloud agent tasks delegated, next session planned

Activities: - Migrated legacy devlog entries (Oct 6 & 8) to project_history_oct_2025.md - Removed forward-looking "Next Phase Priorities" from history doc (purely historical now) - Renamed docs/history/ → docs/legacy/ (43 files initially) - Refined structure: Separated history narratives from legacy artifacts - Created docs/history/ for synthesized historical narratives - Moved project_history_oct_2025.md from legacy/ to history/ - Created history_hub.md explaining active→synthesis→history pattern - Updated legacy_hub.md to be artifact-only index (points to history hub) - Enhanced WebRTC blocker in MVP roadmap Known Gaps section - Deleted duplicate legacy devlog (docs/research/devlog.md) - Discarded superseded status docs (README changes, where_we_are_oct13.md) - Created cloud agent issues for mechanical cleanup tasks: - Issue #22: Obsidian docs → docs/tools/obsidian/ - Issue #23: src/ docs → docs/software/packages/ - Created next session plan: docs/development/work_plan_oct15.md

Commits: - e87bd5b - docs(legacy): reorganize history → legacy, migrate devlog - f17d31d - docs(devlog): document legacy archive reorganization - 56c443e - docs(history): separate history narratives from legacy artifacts - c22b6d1 - docs(planning): create next session plan and update devlog - a39b5c9 - docs(planning): rename next_session.md to work_plan_oct15.md

Final Structure:

docs/
├── history/                    # Synthesized historical narratives
│   ├── history_hub.md         # Index and pattern explanation
│   └── project_history_oct_2025.md  # Oct 3-13 comprehensive narrative (CLOSED)
│
├── development/                # Active tracking
│   ├── devlog.md              # Daily log (Oct 14+) **THIS FILE**
│   └── recent_work.md         # Last 5 days summary
│
├── legacy/                     # Raw historical artifacts
│   ├── legacy_hub.md          # Artifact index (points to history/)
│   └── [41 granular docs]     # Day-by-day working docs from Oct 3-13
│
└── project_overview/           # Goals & planning
    └── mvp_embodied_ai_platform.md  # Current roadmap

Key Decisions: - Three-tier structure: history/ (narratives) ↔ development/ (active) ↔ legacy/ (artifacts) - Pattern established: devlog (active) → periodic synthesis → history doc (closed) - History docs are closed retrospectives, devlog is ongoing chronicle - Legacy artifacts are raw materials that informed history synthesis - Clear separation prevents confusion about where to add/find content - Documentation consolidation pattern: root README acts as quick reference linking to detailed docs under docs/

Discoveries: - Initial attempt lumped narratives with artifacts (confusing) - History doc doesn't belong in legacy/ (it's a synthesis, not an artifact) - Need explicit pattern documentation (history_hub.md explains it)

Next Steps: - Tomorrow (Oct 15): Interactive tasks (project_overview cleanup, development dir organization) - Cloud agents: Handle mechanical tasks (#22 Obsidian, #23 src/ docs) - Later: Legacy mining (review 41 docs for missed info - iterative, do last) - Handle dimos-unitree submodule update (verify if intentional)

Notes: - This structure scales: future histories join history/, devlog keeps growing - Clear semantics: history = past (closed), development = present (active), legacy = artifacts (reference) - Pattern supports long-term project evolution

Evening: MVP Definition & Requirements Gathering (15:00-18:00 PDT / 22:00-01:00 UTC Oct 14)

  • 56c443e - docs(history): separate history narratives from legacy artifacts
  • 4e86f03 - docs(devlog): update with final three-tier structure

Pushed to origin/dev: 12 commits total (including MVP work from earlier session)

Final Structure:

docs/
├── history/                    # Synthesized historical narratives
│   ├── history_hub.md         # Index and pattern explanation
│   └── project_history_oct_2025.md  # Oct 3-13 comprehensive narrative (CLOSED)
│
├── development/                # Active tracking
│   ├── devlog.md              # Daily log (Oct 14+) **THIS FILE**
│   └── recent_work.md         # Last 5 days summary
│
├── legacy/                     # Raw historical artifacts
│   ├── legacy_hub.md          # Artifact index (points to history/)
│   └── [41 granular docs]     # Day-by-day working docs from Oct 3-13
│
└── project_overview/           # Goals & planning
    └── mvp_embodied_ai_platform.md  # Current roadmap

Key Decisions: - Three-tier structure: history/ (narratives) ↔ development/ (active) ↔ legacy/ (artifacts) - Pattern established: devlog (active) → periodic synthesis → history doc (closed) - History docs are closed retrospectives, devlog is ongoing chronicle - Legacy artifacts are raw materials that informed history synthesis - Clear separation prevents confusion about where to add/find content

Discoveries: - Initial attempt lumped narratives with artifacts (confusing) - History doc doesn't belong in legacy/ (it's a synthesis, not an artifact) - Need explicit pattern documentation (history_hub.md explains it)

Next Steps: - Tomorrow (Oct 15): Interactive tasks (project_overview cleanup, development dir organization) - Cloud agents: Handle mechanical tasks (#22 Obsidian, #23 src/ docs) - Later: Legacy mining (review 41 docs for missed info - iterative, do last) - Handle dimos-unitree submodule update (verify if intentional)

Notes: - This structure scales: future histories join history/, devlog keeps growing - Clear semantics: history = past (closed), development = present (active), legacy = artifacts (reference) - Pattern supports long-term project evolution - Documentation consolidation pattern: root README acts as quick reference linking to detailed docs under docs/

Evening: MVP Definition & Requirements Gathering (18:00-21:00)

Type: Planning + Documentation
Status: ✅ Complete
Impact: Complete MVP roadmap defined for household assistant robot

Activities: - Systematic requirements gathering across 5 capability areas - Vision/Perception: DIMOS stack available, VLM branch ready, will experiment - Voice Interface: TTS/STT strategy defined, hardware planned - Navigation/SLAM: "Birth→Learn→Remember" strategy, semantic mapping approach - Compute Budget: Unknown, large effort expected, fallback options identified - Personality System: Configurable personas (Tachikoma, TARS), runtime parameters

Key Decisions: - MVP Goal: "Find the red ball in living room" or "Check if oven is on" - Development phases: Laptop dev → Onboard deployment - Personality: Fixed per persona (MVP), evolving personality (backlog) - Personality scope: Voice responses initially, decision-making (stretch) - Compute fallbacks: Cloud, local GPU workstation, or Orin Nano Super

Files Created: - docs/project_overview/mvp_household_assistant.md (comprehensive roadmap)

Discoveries: - DIMOS perception stack comprehensive but completely untested - VLM branch (Qwen) ready but not merged or tested - Thor compute budget unknown, needs profiling - TARS-style personality parameters (humor, honesty, etc.) resonates with user

Next Steps: - Milestone 1: Vision Foundation (test DIMOS vs VLM) - Milestone 2: Voice Interaction (TTS/STT + personality) - Milestone 3: Semantic Navigation (room understanding) - Milestone 4: Compute Optimization (Thor profiling) - Milestone 5: Integration & Validation (end-to-end)

Notes: - User emphasized staying high-level for roadmap creation - Multiple course corrections to avoid premature implementation details - Clear separation: What needs to be done vs How to implement it - Experimental mindset: Will test approaches and choose based on results

2025-10-13 (Monday)

Evening: Project History & Context Alignment (19:00-21:00)

Type: Documentation
Status: ✅ Complete
Impact: Comprehensive project history documented, ready for goal alignment

Activities: - Created comprehensive project history document (869 lines) - Analyzed 389 commits over 10 days (Oct 3-13) - Documented all major milestones and achievements - Corrected misconceptions about system state - Validated configuration system (.env vs YAML)

Key Discoveries: - Skills exist in DIMOS MyUnitreeSkills (~30 behaviors) - System works end-to-end with physical robot (OpenAI + vLLM tested) - WebRTC API issues block majority of skills (constraint documented) - Configuration uses .env files (YAML configs are legacy/unused) - Custom web UI built from scratch (479 LOC FastAPI)

Commits: Multiple iterations on project_history_oct_2025.md

Notes: - User going to gym, will return to align on project goals - Next session: Define project goals and map next phases based on accomplishments - Devlog system being implemented to improve tracking

Afternoon: DIMOS Documentation & Architecture (14:00-18:00)

Type: Documentation + Upstream Contribution
PR: #8 (DIMOS)
Issue: #7 (DIMOS)
Status: ✅ Complete
Impact: 6,271 lines contributed to DIMOS upstream, architecture clarity achieved

Activities: - Created DIMOS Issue #7 for documentation gaps - Cloud agent created PR #8 with comprehensive DIMOS docs - Reviewed and approved 6,271 lines of documentation - Created agent-robot decoupling analysis (584 lines) - Clarified Mission Agent vs Mission Executor roles (454 lines) - Documented MockRobot strategy for development velocity

Files Created/Updated: - docs/architecture/mission_agent_vs_executor.md (1,000+ lines) - docs/development/agent_robot_decoupling_analysis.md (584 lines) - DIMOS upstream: 10 guide files + 2 API references

Commits: - f1de0c1 - Agent-robot decoupling analysis - 864ab08 - Mission Agent vs Executor clarification - c051cae - Comprehensive inline + external documentation - 2b9c8a5 - DIMOS PR #8 review

Decisions: - MockRobot is critical for development velocity (next priority) - MissionExecutor should be renamed to RobotAgent (future refactor) - Testing pyramid: Mock skills → Mock robot → Gazebo → Hardware

Notes: Architecture now crystal clear, ready for implementation phase

Mid-Afternoon: Project Management (13:00-14:00)

Type: Process Improvement
Status: ✅ Complete
Impact: Project management aligned with reality, issue templates created

Activities: - Created comprehensive cloud agent collaboration workflow - Built issue templates (cloud agent, feature, bug) - Documented project management reality check - Created ideas backlog

Files Created: - docs/development/cloud_agent_workflow.md (600+ lines) - .github/ISSUE_TEMPLATE/ (3 templates) - docs/project_overview/ideas_backlog.md

Commits: - 9b4d772 - Cloud agent collaboration workflow - 8b39173 - Issue templates - 9504fe5 - Project management reality check - 1bf7c4f - Ideas backlog

Notes: Cloud agent workflow proven (8x velocity on documentation tasks)

Morning: Documentation Pipeline Reversal (09:00-13:00)

Type: Infrastructure + Documentation
PR: #21
Issue: #20
Status: ✅ Complete
Impact: 8x velocity improvement on documentation tasks

Activities: - Reversed pipeline: Standard Markdown → Obsidian vault generation - Created tools/obsidian_convert.py for wikilink conversion - Created scripts/generate_obsidian_vault.sh automation - Updated CI pipeline for new workflow - Removed 165k lines of accidental artifacts - Cloud agent executed 6-phase implementation

Commits: - 05e16cf - Prep for Issue #20 - 3e0bbae → 55b111f → 3b07c47 → 9f8b9ae → cdb39a9 → f88f2ee - Cloud agent phases - 19e6017 - Merged PR #21 - 2fa7b46 - Feature complete

Decisions: - Standard Markdown is source of truth (not Obsidian) - Obsidian vault generated on-demand (gitignored) - Documentation authoring simplified significantly

Notes: Proof that cloud agents work well for well-defined tasks with clear acceptance criteria

End of Day Summary

Completed: - ✅ Documentation pipeline reversal (PR #21) - ✅ DIMOS documentation contribution (PR #8, 6,271 lines) - ✅ Architecture clarity documents (1,500+ lines) - ✅ Project management workflows established - ✅ Comprehensive project history documented

In Progress: - Devlog system implementation - Agent instruction updates

Blocked By: None

Tomorrow: - Align on project goals with user - Map next phases based on accomplishments - Define development priorities

Velocity: 29 commits today, 7 major achievements

2025-10-12 (Sunday)

All Day: Massive Documentation Cleanup (09:00-22:00)

Type: Documentation Organization
Status: ✅ Complete
Impact: 187 markdown files organized, Obsidian graph optimized

Activities:

Morning (09:00-12:00): Obsidian Graph Optimization - Optimized Obsidian graph view with colors and physics - Fixed graph phantom nodes - Fixed broken markdown links - Created graph config persistence guide - Created hubs for every topic area

Afternoon (13:00-18:00): Directory-by-Directory Cleanup - Hardware docs organization - Networking docs enhancement - Development docs reorganization (8 legacy → history) - Software docs major reorganization (15 legacy → history) - Troubleshooting docs organization (5 historical → history) - Remaining directories quick pass

Evening (18:00-22:00): Final Consolidation - Project overview consolidation - Improved Obsidian graph usability - Moved project root docs to topic folders - Normalized all filenames to snake_case - Final cleanup and pipeline reversal proposal

Commits: 70 commits (documentation marathon!) - 81c8f3c → b41b3d4 - Graph optimization - c985a3f - Fix phantom nodes - 0669c6a - Fix broken links - de49658 - Graph persistence guide - 0f0289b - Hardware docs - c75a015 - Networking docs - b58c6d0 - Development docs - 9340213 - Software docs reorganization - 9c7fcd5 - Troubleshooting docs - 5fdcfaf - Remaining directories - 1c58c7c - Project overview consolidation - cd23b86 - Graph usability - a92b4c1 / 7d3ec47 - Root docs to folders - 3d7f4a3 - snake_case normalization - 92cbf1c - Pipeline reversal proposal

Achievements: - 187 markdown files organized - Hub structure for navigation - Obsidian graph view optimized - Historical docs archived - Consistent front-matter

Notes: Worth the investment - documentation is now highly navigable and maintainable

End of Day Summary

Completed: ✅ Complete documentation system overhaul (187 files organized)
Velocity: 70 commits, highest single-day commit count

2025-10-11 (Saturday)

All Day: Submodule Conversion (10:00-18:00)

Type: Infrastructure
Status: ✅ Complete
Impact: Simplified dependency management, better IDE support

Activities: - Converted from vcstool to git submodules - Created submodule policy documentation - Created DIMOS branch consolidation plan - Built automated laptop sync script - Updated QUICKSTART_DIMOS for submodules

Commits: ~30 commits - fbe527e / af0652a - Convert to git submodules - 3a0fb53 - Reorganize scripts/docs, add submodule policy - 99469f6 - Update QUICKSTART_DIMOS - 4bad07a - Automated laptop sync script - 5d918b1 - DIMOS branch consolidation plan - 86b2621 - DIMOS branch consolidation script

Decisions: - Git submodules over vcstool (simpler, more standard, better IDE support) - Submodule policy: never edit submodule files directly, fork if needed

Files Created: - docs/policies/submodule_policy.md - scripts/sync_laptop.sh - scripts/consolidate_dimos_branches.sh

Notes: Git submodules provide significantly better developer experience than vcstool

End of Day Summary

Completed: ✅ Submodule conversion complete
Velocity: 30 commits

2025-10-10 (Friday)

All Day: Local LLM Integration Marathon (09:00-22:00)

Type: Feature + Integration
Status: ✅ Complete
Impact: Local LLM backend working, 24x faster than cloud

Activities: - Integrated vLLM backend on Thor AGX - Implemented local embeddings (SentenceTransformers) - Created tool calling validation for multiple models - Extensive model testing (Llama, Mistral, Qwen, Hermes) - Fixed DIMOS auto-creating OpenAI memory with local LLMs - Documented local AI implementation status

Models Tested: - ❌ Llama 3.1 8B (license issues, tokenizer hang) - ✅ Mistral 7B (Apache 2.0, tool calling works) - ❌ Qwen (JSON text instead of execution) - ❌ Hermes-2-Pro (attempted but switched)

Commits: ~60 commits (intense day!) - 3c4f04e - DIMOS agent architecture reference - 7ced3ff - Roadmap for fully local AI agent with memory - b0c0e26 - Local embeddings test script - d9b6340 - Fixed DIMOS OpenAI memory with local LLMs - 0b2da03 → ca48cf3 → 16be165 - Model experiments - 3ac1e01 - Local LLM support + agent improvements - 45618b2 - Local AI implementation status report

Files Created: - test_embeddings_fix.py - docs/software/llm/thor_performance_notes.md - docs/architecture/local_ai_roadmap.md

Decisions: - Mistral 7B selected for local deployment (Apache 2.0, tool calling works) - Local embeddings (sentence-transformers) default for non-OpenAI backends - vLLM on Thor AGX proven viable (37 tok/s baseline)

Notes: Local LLM provides 24x speed improvement over cloud (0.5s vs 12s per query)

End of Day Summary

Completed: ✅ Local LLM integration working
Velocity: 60 commits (peak day for features)

2025-10-09 (Thursday)

Afternoon-Evening: Network Architecture & Integration Merge (14:00-20:00)

Type: Documentation + Integration
PR: feature/dimos-integration merge
Commit: f16bda8
Status: ✅ Complete
Impact: DIMOS integration validated on hardware and merged

Activities: - Documented desktop/laptop/Thor architecture - Created sync workflows between machines - Created network topology diagrams - Documented DDS communication patterns - Merged feature/dimos-integration after successful robot tests

Commits: ~40 commits - f16bda8 - Feature/dimos-integration merge (VALIDATED ON HARDWARE!) - 3c4ed3a - Desktop/laptop/thor architecture and sync workflow - 48da89e - Laptop host sync script - caa4d8a - Improved sync script for uncommitted changes

Files Created: - docs/networking/desktop_laptop_thor_architecture.md - scripts/sync_laptop_host.sh - Network topology diagrams

Decisions: - Feature branch validated on physical robot before merge (de-risks architecture changes) - Multi-machine development workflow documented from hands-on experience

Notes: Major milestone - DIMOS integration proven on hardware

End of Day Summary

Completed: ✅ DIMOS integration merged after hardware validation
Velocity: 40 commits

2025-10-07 to 2025-10-08 (Mon-Tue)

Configuration & Hardware Testing

Type: Configuration + Testing
Status: ✅ Complete
Impact: Robot tested with multiple backends, configuration system working

Activities: - Created multiple backend configurations (cloud OpenAI, local Ollama) - Implemented environment variable management (.env files) - Enhanced start script with backend validation - Created laptop setup guides for hardware testing - Tested on physical Unitree Go2

Commits: ~30 commits - bfa27bf - Pin dimos-unitree to specific commit - 6b8dd2c - Laptop setup guide for real robot testing - 0affcbe - Known issues and troubleshooting guide (from real testing!)

Files Created: - .env.example (300+ lines comprehensive template) - .env.development - .env.production - docs/deployment/laptop_dev_setup.md

Discoveries: - Hardware testing reveals real constraints and configuration needs - Configuration iterating based on real-world usage - WebRTC API issues discovered on physical robot

Notes: Hardware testing in progress during DIMOS integration development

End of Period Summary

Completed: ✅ Configuration system working, robot tested
Velocity: 30 commits

2025-10-05 to 2025-10-06 (Sat-Sun)

DIMOS Integration Branch + Custom Web UI

Type: Feature + Integration
Branch: feature/dimos-integration
Status: ✅ Complete (merged Oct 9)
Impact: Mission agent architecture implemented (~2,100 LOC)

Activities: - Built custom FastAPI web interface from scratch (479 LOC) - Implemented mission agent ROS2 node (713 LOC) - Implemented mission executor cognitive layer (517 LOC) - Created RAG memory examples (392 LOC) - Created launch files and configuration - Created comprehensive documentation

Commits: ~50 commits - f6b5a6a - Mission agent design documentation - 26d25fa - DIMOS web interface integration options - 7159e5a - Architecture: DIMOS agent vs ROS node - eeaa03a - Embedded web interface (built from scratch!) - 54ea06a - ChatGPT API integration - 90ddaac - RAG integration guide - 10a1b2a - Environment configuration system - 45a04f5 - Comprehensive start script

Files Created: - src/shadowhound_mission_agent/shadowhound_mission_agent/mission_agent.py (713 lines) - src/shadowhound_mission_agent/shadowhound_mission_agent/mission_executor.py (517 lines) - src/shadowhound_mission_agent/shadowhound_mission_agent/web_interface.py (479 lines) - src/shadowhound_mission_agent/shadowhound_mission_agent/rag_memory_example.py (392 lines) - start.sh (comprehensive orchestrated launch)

Decisions: - Build custom web UI rather than integrate DIMOS web interface (full control) - Feature branch for DIMOS integration (validate before merging) - Separate mission agent (ROS) from mission executor (cognitive layer)

Notes: Custom web UI gives full control and understanding, not tied to DIMOS implementation

End of Period Summary

Completed: ✅ Mission agent architecture complete (~2,100 LOC)
Velocity: 50 commits

2025-10-04 to 2025-10-05 (Thu-Fri)

Core ROS2 SDK Stabilization

Type: Infrastructure
Status: ✅ Complete
Impact: Stable foundation for all subsequent work

Activities: - Significant effort stabilizing go2_ros2_sdk - Created initial architecture documentation - Stabilized ROS2 bridge to hardware - Documented hardware communication patterns - Created package structure

Commits: ~40 commits - a2238ea - Architecture redesign leveraging DIMOS - 4e4f229 - Initial DIMOS project setup documentation - 7e75172 - DIMOS capabilities documentation - 32ec845 - shadowhound_mission_agent package created - ee63a5f - shadowhound_bringup package created

Files Created: - src/shadowhound_mission_agent/ (package structure) - src/shadowhound_bringup/ (package structure) - Architecture documentation (multiple files)

Decisions: - Leverage DIMOS framework for agent capabilities - Four-layer architecture (Application, Agent, Skills, Robot) - Separation of concerns: ROS wrapper vs cognitive layer

Notes: Foundation work is invisible but critical - enabled rapid feature development

End of Period Summary

Completed: ✅ ROS2 SDK stable, ready for DIMOS integration
Velocity: 40 commits

2025-10-03 to 2025-10-04 (Wed-Thu)

Initial Project Setup

Type: Infrastructure
Status: ✅ Complete
Impact: Working development environment

Activities: - Created devcontainer with ROS2 Humble - Integrated go2_ros2_sdk - Set up initial project structure - Created basic documentation - Configured build system (colcon)

Commits: ~50 commits - f42f199 - Initial Dockerfile and setup script - dcc35d1 - Enhanced development environment - 0d633fa - Project context documentation

Files Created: - .devcontainer/ configuration - Initial README.md - Basic project structure

Decisions: - Use devcontainer for reproducible development environment - ROS2 Humble as base distribution - CycloneDDS as middleware

Notes: Empty workspace → Buildable ROS2 environment in 2 days

End of Period Summary

Completed: ✅ Development environment working
Velocity: 50 commits

Template for Future Entries

Simple Work (Lightweight Entry)

### [Time]: [Activity Name]
**Type**: Feature | Fix | Documentation | Refactor
**Status**: ✅ Complete
**Experiment Doc**: [experiments/name.md](experiments/name.md) (if applicable)

Brief description of what was done and key results.

**Key Results**:
- Bullet list of outcomes
- Performance metrics if applicable

**Commits**: `abc123`, `def456`

Experimental Work (Create Experiment Doc + Pointer)

### [Time]: [Experiment Name]
**Type**: Feature | Research | Integration
**Status**: ✅ Complete
**Experiment Doc**: [experiments/{feature}_{topic}_{date}.md](experiments/{feature}_{topic}_{date}.md)

One-sentence summary of the experiment and outcome.

**Key Results**:
- What worked
- Key metrics
- Final decision

**Commits**: `abc123`, `def456`

Then create detailed experiment doc at: docs/development/experiments/{feature}_{topic}_{date}.md

Use template: docs/development/experiments/template_experiment.md

Devlog Guidelines for Agents

When to Create Experiment Doc vs Simple Devlog Entry

Use Experiment Doc (experiments/{name}.md) when: - ✅ Testing multiple approaches (e.g., 4 LLM models) - ✅ Feature branch spans multiple days - ✅ Extensive debugging or investigation - ✅ Need to document "what we tried" not just "what worked" - ✅ Research-driven development with exploration

Use Simple Devlog Entry when: - ✅ Straightforward feature implementation - ✅ Bug fix with clear solution - ✅ Documentation updates - ✅ Refactoring with no exploration - ✅ Mechanical tasks (file moves, config updates)

How to Update

For Simple Work: 1. Add lightweight entry to this file (at top, most recent first) 2. Include: time, type, status, key results, commits 3. Commit: docs(devlog): [activity title]

For Experimental Work: 1. Create experiment doc: experiments/{feature}_{topic}_{date}.md 2. Use template: experiments/template_experiment.md 3. Document: Context, Hypothesis, Experiments, Final Results 4. Add pointer entry to this file (lightweight) 5. Commit experiment doc: docs(experiments): [title] 6. Commit devlog update: docs(devlog): [title]

See Also

Last Updated: 2025-10-14
Pattern Established: Oct 14, 2025 (Experiment documentation system created) Total Entries: 15+ (Oct 3-14, 2025)