---
id: hatch3r-learning-consult
type: rule
description: Consult .hatch3r/learnings/ for pitfalls, patterns, and past decisions before implementation with frontmatter-first scan and priority ordering
scope: "**/.hatch3r/learnings/**,**/learnings/**"
tags: [orchestration]
quality_charter: agents/shared/quality-charter.md
cache_friendly: true
---
# Learning Consultation

Before implementing any task, check `.hatch3r/learnings/` for relevant past learnings.

## Consultation Process

1. If `.hatch3r/learnings/` exists and contains files:
   - Scan learning file frontmatter for matching `tags` or `area` that overlap with the current task.
   - Read the `## Applies When` section of potential matches.
   - Surface relevant learnings to the developer/agent before implementation begins.
2. If no learnings directory exists, skip silently.

## Integration Points

- During `hatch3r-board-pickup` Step 6: consult learnings before implementation delegation.
- During `hatch3r-board-fill` Step 4: consult learnings when scoping and estimating issues.
- During the `hatch3r-board-groom` skill (Step 4c): consult learnings when re-scoping or reclassifying existing issues.
- During any skill execution: check for relevant pitfalls before coding.

## Learning Priority

- **Pitfalls** are highest priority -- always surface these.
- **Patterns** are surfaced when the current task matches their trigger conditions.
- **Decisions** are surfaced when the current task might conflict with a past decision.

## Consultation Efficiency

To avoid excessive token usage during consultation:

1. **Scan frontmatter first.** Read only the YAML frontmatter (`tags`, `area`, `category`) of each learning file to determine relevance. Only read the full body of learnings that match the current task.
2. **Limit surfaced learnings.** Present at most 5 relevant learnings per consultation. If more are relevant, prioritize by confidence level (high > medium > low) and recency.
3. **Cache consultation results.** If consultation was already performed for this task (e.g., during board-pickup), do not re-consult during skill execution. The orchestrator passes relevant learnings to subagents as part of prompt enrichment.
4. **Skip when empty.** If `.hatch3r/learnings/` has fewer than 3 files, consultation overhead exceeds value. Skip silently.
