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:

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.