/implementation-logger

name: "implementation-logger"
description: "Log implementation decisions — tracks deviations from plan and captures rationale"
license: "MIT"
compatibility: "cline, claude, opencode, amp, codex, gemini, cursor, pi"
hint: "Use during implementation of complex or uncertain changes to track decisions"
user-invocable: true

Implementation Logger

When to Use

Use this skill **during implementation** when:

• Working on complex or uncertain changes
• The implementation approach isn't fully defined
• You want to track decisions for documentation
• Building knowledge about unknowns for future work
• Need to explain reasoning in PR descriptions

What It Does

Tracks **deviations from the original plan** and **decision rationale** during implementation. Helps identify where your mental model (map) differed from reality (territory).

How to Execute

Step 1: Set Up Logging

At the start of implementation, create a log file:

# Create implementation log
echo "# Implementation Log: [Feature Name]" > .implementation-log.md
echo "" >> .implementation-log.md
echo "Started: $(date)" >> .implementation-log.md
echo "" >> .implementation-log.md
echo "## Original Plan" >> .implementation-log.md
echo "[Brief summary of approach]" >> .implementation-log.md
echo "" >> .implementation-log.md
echo "## Deviations & Decisions" >> .implementation-log.md

Step 2: Log During Implementation

Whenever reality differs from plan, log it:

### [Timestamp] - [Decision Point Title]

**Context**: What I encountered that wasn't in the plan

**Original Assumption**: What I thought would work

**Reality**: What I actually found

**Decision**: What I decided to do instead

**Rationale**: Why this approach is better/necessary

**Impact**: What else this might affect

Step 3: Log Categories

Track different types of deviations:

**Architectural Discoveries**:

• Found existing abstraction that changes approach
• Realized need for new pattern
• Dependency constraints

**Unknown Unknowns**:

• Edge cases not in spec
• Integration points discovered
• Performance considerations

**Technical Constraints**:

• Library limitations
• Type system issues
• Test infrastructure gaps

**Spec Gaps**:

• Ambiguous requirements
• Missing error handling specs
• Unclear business logic

Step 4: Review & Extract

After implementation: 1. Review the log for patterns 2. For each material deviation, compare `expected -> observed -> decision -> verified result` 3. Extract only durable learnings for documentation or skills 4. Identify knowledge to preserve 5. Record "No material deviations" when the plan held; do not invent entries 6. Update relevant docs/ADRs

Log Template

# Implementation Log: [Feature Name]

**Date**: [Date]
**Developer**: [Name or Agent ID]
**Original Plan**: [Link to spec/plan]

## Summary
[One paragraph: what we built and key decisions]

## Original Approach
[What we planned to do]

## Deviations & Decisions

### Decision 1: [Title]
**When**: [Timestamp/phase]
**Context**: [What prompted this decision]
**Original Plan**: [What we thought we'd do]
**Reality**: [What we actually found]
**Decision**: [What we decided]
**Rationale**: [Why this is better]
**Impact**: [Side effects or dependencies]
**Code**: [Link to relevant commit/files]

### Decision 2: [Title]
...

## Unknowns Discovered

### Unknown: [Title]
**Category**: [Architecture/Spec/Technical/Business]
**Impact**: [High/Medium/Low]
**Description**: [What we didn't know]
**Resolution**: [How we resolved it]
**Future Consideration**: [Should this inform future work?]

## Learnings

### What Worked Well
- [Learning 1]
- [Learning 2]

### What Was Surprising
- [Surprise 1]
- [Surprise 2]

### What to Do Differently Next Time
- [Improvement 1]
- [Improvement 2]

## Documentation Updates Needed
- [ ] Update ADR on [topic]
- [ ] Add to MEMORY.md: [learning]
- [ ] Update [skill/guide]: [improvement]

## Follow-up Questions
1. [Question that arose during implementation]
2. [Question for stakeholder/team]

Example Usage

# Implementation Log: GitHub OAuth Integration

**Date**: 2026-07-08
**Original Plan**: docs/specs/github-oauth.md

## Summary
Implemented GitHub OAuth provider following existing OAuth pattern.
Key deviation: Used App Installation flow instead of user OAuth due to
org-level permission requirements. Added webhook endpoint for
installation events.

## Original Approach
- Implement standard OAuth 2.0 flow via library
- Use Personal Access Token (PAT) flow for initial testing

## Deviations & Decisions

### Decision 1: Use GitHub App Installation Flow

**When**: During initial auth flow implementation

**Context**: Testing revealed that org-level repo access requires GitHub
App installation, not user OAuth. Our target users need org repo access.

**Original Plan**: Standard OAuth with PAT

**Reality**: GitHub deprecated PAT for org access. Apps must use
Installation flow which requires:
- App installation per organization
- Installation webhook handling
- Installation-specific tokens

**Decision**: Implement GitHub App Installation flow instead

**Rationale**:
- Only way to get org-level repo access
- More secure (granular permissions)
- Better aligned with GitHub's current best practices
- Matches what users expect (seen in other tools)

**Impact**:
- Added webhook endpoint: /webhooks/github/installation
- New database table: github_installations
- Installation token refresh logic (expires after 1hr vs 6mo)
- More complex setup docs (users must create GitHub App)

**Code**: commit abc123, files: auth/github/installation.ts

### Decision 2: Cache Installation Tokens

**When**: During token refresh implementation

**Context**: Installation tokens expire after 1 hour. Naive approach would
request new token for every API call.

**Original Plan**: Request new token on each API call

**Reality**: GitHub rate limits token requests to 5000/hour per app.
With multiple users in same org, we