Gpd Record Insight

<execution_context>

<required_reading> Read all files referenced by the invoking prompt's execution_context before starting. </required_reading>

test -f .gpd/INSIGHTS.md && echo "EXISTS" || echo "MISSING"

If MISSING: Create from template:

mkdir -p .gpd

Write .gpd/INSIGHTS.md:

# Project Insights

Accumulated project-specific lessons discovered during research. Agents consult this file to avoid repeating mistakes and to apply learned patterns.

## Debugging Patterns

| Date | Phase | Category | Confidence | Description | Prevention |
| ---- | ----- | -------- | ---------- | ----------- | ---------- |

## Verification Lessons

| Date | Phase | Category | Confidence | Description | Prevention |
| ---- | ----- | -------- | ---------- | ----------- | ---------- |

## Consistency Issues

| Date | Phase | Category | Confidence | Description | Prevention |
| ---- | ----- | -------- | ---------- | ----------- | ---------- |

## Execution Deviations

| Date | Phase | Category | Confidence | Description | Prevention |
| ---- | ----- | -------- | ---------- | ----------- | ---------- |

grep -i "{brief_description_keyword}" .gpd/INSIGHTS.md 2>/dev/null

If found: Do not duplicate. Report: "Insight already recorded." If not found: Proceed to append. </step>

Row format:

| {YYYY-MM-DD} | {phase-id} | {category} | {high/medium/low} | {concise description of the lesson} | {how to prevent recurrence} |

Field guidelines:

• Date: ISO date of discovery
• Phase: Phase where the insight was discovered (e.g., 03-numerics)
• Category: One of: error-pattern, convention-pitfall, approximation-lesson, computational-insight, debugging-pattern, verification-lesson
• Confidence: high (confirmed with evidence), medium (likely based on investigation), low (suspected pattern, needs more data)
• Description: One sentence capturing the lesson. Be specific: "Sign error in Wick contractions when using mostly-minus metric" not "sign errors happen"
• Prevention: One sentence on how to avoid this in future phases </step>

PRE_CHECK=$(/home/qol/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local pre-commit-check --files .gpd/INSIGHTS.md 2>&1) || true
echo "$PRE_CHECK"

/home/qol/.gpd/venv/bin/python -m gpd.runtime_cli --runtime codex --config-dir ./.codex --install-scope local commit "docs: record project insight - {brief description}" --files .gpd/INSIGHTS.md

Confirm: "Recorded insight: {brief description}" </step>

<success_criteria>

• .gpd/INSIGHTS.md exists (created if needed)
• No duplicate insight recorded
• Insight appended to correct section with all fields populated
• Committed to git with descriptive message

Lifecycle note: High-confidence insights confirmed across 2+ phases are candidates for promotion to the global pattern library at milestone completion ($gpd-complete-milestone → promote_patterns step). Set confidence accurately — it determines promotion eligibility.

</success_criteria>

</execution_context>

The workflow handles all logic including:

1. Checking/creating .gpd/INSIGHTS.md
2. Duplicate detection
3. Determining the correct section (Debugging Patterns, Verification Lessons, Consistency Issues, Execution Deviations)
4. Appending structured table row with date, phase, category, confidence, description, prevention
5. Git commit