# Observability > Logs AI thoughts and decisions for human observability. Applies continuously throughout all tasks to maintain transparency. Use when this capability is needed. - Skill: `tomevault-io/observability-3` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/observability-3` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/observability-3/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/observability-3 --- # Observability Skill Maintain transparent, human-readable logs of AI decision-making process. ## Workspace Mode Note When running in workspace mode, log to `.aha-loop/logs/ai-thoughts.md` instead of `logs/ai-thoughts.md`. The orchestrator will provide the actual paths in the prompt context. --- ## The Job 1. Log significant thoughts and decisions to `logs/ai-thoughts.md` 2. Provide visibility into AI reasoning process 3. Create anchors for humans to understand what's happening 4. Never hide failures or uncertainty --- ## When to Log ### Always Log - **Starting a new task** - What am I about to do and why - **Major decisions** - When choosing between approaches - **Unexpected findings** - Something surprising or important - **Errors and recovery** - What went wrong and how I'm handling it - **Completion** - What was accomplished ### Optional Log (Detailed Level) - Intermediate steps - Research findings - Minor decisions - Progress updates --- ## Log Format Append to `logs/ai-thoughts.md`: ```markdown ## 2026-01-29 14:30:00 | Task: PRD-003 | Phase: Research ### Context I'm researching authentication strategies for the web app. This is critical because it affects security architecture and user experience. ### Inner Thoughts The vision mentions "simple" and "quick to use". Traditional username/password might add friction. Considering passwordless options but need to evaluate complexity tradeoffs. ### Decision Point - Considering: Traditional email/password - Considering: Magic link (passwordless) - Considering: OAuth only (Google/GitHub) - **Chosen:** Magic link with OAuth fallback - **Reason:** Aligns with "simple" goal, reduces password fatigue, OAuth provides familiar alternative ### Current Progress - [x] Read vision requirements - [x] Research auth options - [ ] Prototype magic link flow - [ ] Evaluate email service options ### Observations - Magic link requires reliable email delivery - Need to consider rate limiting to prevent abuse - Session duration is important for UX ### Next Action Will research email service providers (Resend, SendGrid) and evaluate their free tiers since budget constraint mentioned "no paid APIs". --- ``` --- ## Log Levels Configure in `config.json`: ### Minimal - Task start/end only - Major errors ### Normal (Default) - All major decisions - Phase transitions - Errors and recovery ### Detailed - Everything above - Intermediate thoughts - Research notes - Minor decisions --- ## Thought Categories ### Inner Monologue Express your actual reasoning: - "I'm uncertain about X because..." - "This seems risky because..." - "I'm choosing Y over Z because..." - "I notice that..." ### Decision Points When facing choices: ```markdown ### Decision Point - Considering: [Option A] - [pros/cons] - Considering: [Option B] - [pros/cons] - **Chosen:** [Option] - **Reason:** [Why] - **Tradeoffs:** [What we're giving up] ``` ### Uncertainty Be honest about what you don't know: ```markdown ### Uncertainty I'm not 100% sure about [X]. My current assumption is [Y] because [Z]. If this proves wrong, I'll need to [fallback plan]. ``` ### Errors When things go wrong: ```markdown ### Error Encountered **What happened:** [Description] **Why:** [Root cause if known] **Impact:** [What this affects] **Recovery:** [How I'm handling it] ``` --- ## Principles ### Be Transparent - Don't hide uncertainty - Don't pretend to know what you don't - Admit mistakes openly ### Be Useful - Logs should help humans understand - Avoid jargon without explanation - Provide context ### Be Honest - Express genuine reasoning, not performance - Include doubts and concerns - Note when guessing vs. knowing ### Be Concise - Important details only - No filler text - Structured for scanning --- ## Integration ### At Task Start ```markdown ## [timestamp] | Task: [id] | Phase: Starting ### Context [What I'm about to do] ### Approach [How I plan to tackle it] ### Potential Concerns [What might go wrong] ``` ### At Decision Points ```markdown ### Decision Point [Structured decision format] ``` ### At Task End ```markdown ## [timestamp] | Task: [id] | Phase: Complete ### Summary [What was accomplished] ### Key Decisions Made - [Decision 1] - [Decision 2] ### Learnings [What I learned that might be useful later] ### Concerns for Future [Any issues to watch for] ``` --- ## Example: Full Task Log ```markdown ## 2026-01-29 10:00:00 | Task: PRD-001 | Phase: Starting ### Context Beginning the project scaffolding PRD. This sets up the foundation for the entire project, so I need to be careful about initial decisions. ### Approach 1. First, review the architecture document for tech stack 2. Initialize the project with chosen tools 3. Set up basic structure 4. Configure development environment ### Potential Concerns - Version compatibility between dependencies - Getting the directory structure right from the start --- ## 2026-01-29 10:15:00 | Task: PRD-001 | Phase: Research ### Inner Thoughts The architecture specifies Rust + Axum. I should verify I'm using the latest stable versions. Let me check crates.io... ### Observations - Axum 0.7.4 is latest (released 2 weeks ago, stable) - Tokio 1.35 is latest - Should use workspace structure for future modularity --- ## 2026-01-29 10:30:00 | Task: PRD-001 | Phase: Implementation ### Decision Point - Considering: Single crate structure - Considering: Workspace with multiple crates - **Chosen:** Workspace structure - **Reason:** Project will likely grow, easier to refactor now than later ### Progress - [x] Created Cargo.toml with workspace - [x] Added main crate - [ ] Add configuration - [ ] Add basic error handling --- ## 2026-01-29 11:00:00 | Task: PRD-001 | Phase: Complete ### Summary Successfully set up Rust project with Axum 0.7.4, configured workspace, added basic structure with src/main.rs entry point. ### Key Decisions Made - Workspace structure for scalability - Tokio multi-threaded runtime - Tracing for logging ### Learnings - Axum 0.7 changed some APIs from 0.6, needed to use new Router syntax ### Files Created - Cargo.toml - src/main.rs - src/lib.rs --- ``` --- ## Mindset **You are thinking out loud for human benefit.** Your logs should read like a competent colleague explaining their work: - Clear reasoning - Honest about uncertainty - Proactive about potential issues - Documenting for future reference **Remember:** Humans will read these logs to understand what you did and why. Make their job easy. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/youglin-dev) — claim your Tome and manage your conversions.