name	learn
description	Extract reusable patterns from non-trivial problems solved in a session and store them as reusable project knowledge. Use after complex debugging, architecture discoveries, or practical workarounds.

/learn - Extract Reusable Patterns

Analyze the current session and capture patterns worth reusing in this Remix + React + TypeScript portfolio project.

Auto-Activation Criteria

Consider auto-activating this skill when:

A complex bug was fixed (non-obvious root cause, multi-step diagnosis).
A new implementation pattern was discovered and validated.
A workaround was implemented for a library/framework/platform limitation.
The session is ending and meaningful technical learning was produced (ask user before writing).

Do not activate for:

trivial typo fixes
one-line obvious refactors
temporary external incidents (e.g., transient API outage)
patterns already documented in .codex/skills/learn/learned/

Manual Trigger

Run /learn after resolving a non-trivial issue.

What To Extract

1. Error Resolution Patterns

What failed?
What was the real root cause?
What exact fix worked?
How can the same pattern be reused?

Project-relevant examples:

React state/ref synchronization issues in game loops.
Collision box mismatches vs. rendered visuals.
TypeScript literal type narrowing issues in refs/state.
Asset-driven animation state bugs (timing/order/race).

2. Debugging Techniques

Non-obvious debugging sequence that worked.
Useful command/tool combinations.
Fast diagnosis patterns.

Project-relevant examples:

Using pnpm typecheck + pnpm build after each gameplay logic change.
Comparing style-driven transforms with getBoundingClientRect() collision logic.
Isolating hooks (useGameLoop, useObstacles, useJump) to pinpoint regressions.

3. Workarounds

Framework/library constraints and mitigations.
Version-specific fixes.
Practical tradeoffs that were chosen and why.

Project-relevant examples:

Sprite/background animation fallback instead of SVG internals.
Responsive scaling using legacy baseline ratios.
Clear-state sequence orchestration with phased timers.

4. Project-Specific Patterns

Codebase conventions discovered during implementation.
Architecture decisions and integration boundaries.

Project-relevant examples:

Feature-based structure (features/jump-game/...) and hook boundaries.
Runtime DOM element creation pattern in obstacle systems.
Separation of render state (UI) vs. simulation state (loop refs).

Output Format

Create one file per pattern at:

.codex/skills/learn/learned/[pattern-name].md

Template:

# [Descriptive Pattern Name]

**Captured:** YYYY-MM-DD
**Context:** [When this pattern applies]
**Tags:** react, remix, typescript, game-loop, collision, animation, etc.

## Problem

[Specific recurring problem this pattern solves]

## Solution

[Reusable approach, key decisions, and constraints]

## Example

```ts
// Minimal real example from this codebase
```

When To Use

[Trigger conditions for applying this pattern]

Related Files

features/jump-game/model/useGameLoop.ts
features/jump-game/model/useObstacles.ts
features/jump-game/ui/JumpGame.tsx


## Process

1. Review the session for candidate learnings.
2. Select the highest-value reusable pattern(s).
3. Draft the pattern file.
4. Ask user confirmation before saving.
5. Save to `.codex/skills/learn/learned/`.
6. Update `.codex/skills/learn/LEARNED_INDEX.md` with a one-line entry (required).

Index format:

`- **[pattern-name](learned/pattern-name.md)** - One-line summary.`

## Common Pattern Categories For This Project

- Game loop timing and state synchronization
- Collision detection vs. rendered position alignment
- Responsive scaling from fixed-pixel legacy assumptions
- Sprite animation sequencing and transitions
- Boss/obstacle/fish spawn balancing and fail-state prevention
- TypeScript safety for refs, unions, and hook contracts

## Notes

- Capture only non-trivial, reusable patterns.
- Keep one pattern per file.
- Prefer concrete examples from this repository.
- Keep entries short, searchable, and implementation-focused.

name	learn
description	Extract reusable patterns from non-trivial problems solved in a session and store them as reusable project knowledge. Use after complex debugging, architecture discoveries, or practical workarounds.

/learn - Extract Reusable Patterns

Analyze the current session and capture patterns worth reusing in this Remix + React + TypeScript portfolio project.

Auto-Activation Criteria

Consider auto-activating this skill when:

A complex bug was fixed (non-obvious root cause, multi-step diagnosis).
A new implementation pattern was discovered and validated.
A workaround was implemented for a library/framework/platform limitation.
The session is ending and meaningful technical learning was produced (ask user before writing).

Do not activate for:

trivial typo fixes
one-line obvious refactors
temporary external incidents (e.g., transient API outage)
patterns already documented in .codex/skills/learn/learned/

Manual Trigger

Run /learn after resolving a non-trivial issue.

What To Extract

1. Error Resolution Patterns

What failed?
What was the real root cause?
What exact fix worked?
How can the same pattern be reused?

Project-relevant examples:

React state/ref synchronization issues in game loops.
Collision box mismatches vs. rendered visuals.
TypeScript literal type narrowing issues in refs/state.
Asset-driven animation state bugs (timing/order/race).

2. Debugging Techniques

Non-obvious debugging sequence that worked.
Useful command/tool combinations.
Fast diagnosis patterns.

Project-relevant examples:

Using pnpm typecheck + pnpm build after each gameplay logic change.
Comparing style-driven transforms with getBoundingClientRect() collision logic.
Isolating hooks (useGameLoop, useObstacles, useJump) to pinpoint regressions.

3. Workarounds

Framework/library constraints and mitigations.
Version-specific fixes.
Practical tradeoffs that were chosen and why.

Project-relevant examples:

Sprite/background animation fallback instead of SVG internals.
Responsive scaling using legacy baseline ratios.
Clear-state sequence orchestration with phased timers.

4. Project-Specific Patterns

Codebase conventions discovered during implementation.
Architecture decisions and integration boundaries.

Project-relevant examples:

Feature-based structure (features/jump-game/...) and hook boundaries.
Runtime DOM element creation pattern in obstacle systems.
Separation of render state (UI) vs. simulation state (loop refs).

Output Format

Create one file per pattern at:

.codex/skills/learn/learned/[pattern-name].md

Template:

# [Descriptive Pattern Name]

**Captured:** YYYY-MM-DD
**Context:** [When this pattern applies]
**Tags:** react, remix, typescript, game-loop, collision, animation, etc.

## Problem

[Specific recurring problem this pattern solves]

## Solution

[Reusable approach, key decisions, and constraints]

## Example

```ts
// Minimal real example from this codebase
```

When To Use

[Trigger conditions for applying this pattern]

Related Files

features/jump-game/model/useGameLoop.ts
features/jump-game/model/useObstacles.ts
features/jump-game/ui/JumpGame.tsx


## Process

1. Review the session for candidate learnings.
2. Select the highest-value reusable pattern(s).
3. Draft the pattern file.
4. Ask user confirmation before saving.
5. Save to `.codex/skills/learn/learned/`.
6. Update `.codex/skills/learn/LEARNED_INDEX.md` with a one-line entry (required).

Index format:

`- **[pattern-name](learned/pattern-name.md)** - One-line summary.`

## Common Pattern Categories For This Project

- Game loop timing and state synchronization
- Collision detection vs. rendered position alignment
- Responsive scaling from fixed-pixel legacy assumptions
- Sprite animation sequencing and transitions
- Boss/obstacle/fish spawn balancing and fail-state prevention
- TypeScript safety for refs, unions, and hook contracts

## Notes

- Capture only non-trivial, reusable patterns.
- Keep one pattern per file.
- Prefer concrete examples from this repository.
- Keep entries short, searchable, and implementation-focused.