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.

observability