tomevault-io 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
- Log significant thoughts and decisions to
logs/ai-thoughts.md - Provide visibility into AI reasoning process
- Create anchors for humans to understand what's happening
- 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:
## 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:
### 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:
### 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:
### 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
## [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
### Decision Point
[Structured decision format]
At Task End
## [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
## 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 — claim your Tome and manage your conversions.