implementation-logger

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```bash
# 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:

```markdown
### [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

```markdown
# 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

From jellydn/my-ai-tools, MIT.

More from jellydn/my-ai-tools