snqb/backreason

Backreason

Reason backwards from usage patterns to improve project orientation.

Core idea: Don't guess what belongs in AGENTS.md or docs — measure it. Mine past sessions, extract the user's actual vocabulary, compare against what's documented, fix the gaps.

When to Use

• Reconciling AGENTS.md (pair with agents-md skill)
• User asks "what do I keep working on?" or "what's missing?"
• After 20+ sessions in a project — enough signal to analyze
• When AGENTS.md feels stale or bloated — evidence-based trim

Workflow

1. Find Sessions

SESSION_DIR=~/.pi/agent/sessions/--$(pwd | tr '/' '-' | sed 's/^-//')--
ls "$SESSION_DIR"/*.jsonl 2>/dev/null | wc -l

If no sessions found, try fuzzy match:

ls ~/.pi/agent/sessions/ | grep -i "$(basename $(pwd))"

2. Extract Starter Messages

The first user message per session reveals intent — what they came to do.

for f in $(ls -t "$SESSION_DIR"/*.jsonl 2>/dev/null); do
  date=$(basename "$f" | cut -c1-10)
  msg=$(cat "$f" | jq -r 'select(.type == "message") | select(.message.role == "user") | .message.content[0].text' 2>/dev/null | head -1 | cut -c1-120)
  [ -n "$msg" ] && echo "$date | $msg"
done

3. Concept Frequency

Build a grep pattern from project-specific terms. Start broad, then cluster.

# Save starters to temp file first (step 2 output)
cat /tmp/starters.txt | tr '[:upper:]' '[:lower:]' | \
  grep -oE '(term1|term2|term3|...)' | \
  sort | uniq -c | sort -rn | head -30

How to build the term list:

• Scan the starters manually first — note recurring nouns
• Add directory names, file names, feature names from the project
• Include the user's informal names (they say "freshness", code says "staleness")
• Include operational terms (prod, deploy, logs, dashboard)

4. Cluster & Rank

Group related terms into concept clusters. Rank by total mentions.

 #  Cluster              Mentions  User's words
 1  parser/scraping      20        parser, scraping, scraped
 2  bot                  12        bot
 3  photos/collages      10        photos, collage
 ...

5. Coverage Check

Compare top concepts against AGENTS.md (or whatever doc you're improving):

grep -oiE '(term1|term2|...)' AGENTS.md | tr '[:upper:]' '[:lower:]' | sort -u

Build a gap table:

| Concept | Mentions | In docs? | Where it lives | |---------|----------|----------|----------------| | collage | 10 | ❌ | bot/dialogs/ad_browser/getters.py | | zones | 5 | ❌ | bot/shared/districts/kg_zones.py |

6. Fix Gaps

For each missing concept, find where it lives in code:

grep -rl "concept" src/ --include="*.py" | head -5

Then update the doc using the user's vocabulary, not the code's internal naming:

• Code says staleness.py → Map says "Freshness checks — verify active listings still exist"
• Code says getters.py → Map says "photo albums, collages"

Key Principles

Use their words. If the user says "freshness" 4 times and never "staleness", the Map should say "freshness". Alias the code term parenthetically.

Starters reveal priority. The first message is what they came to do. Later messages are follow-ups. Weight starters heavily.

Frequency = importance. If they ask about photos/collages 10 times, it's a core concept — not a detail to bury.

Absence = problem. If a concept appears 5+ times in sessions but 0 times in AGENTS.md, that's a navigation failure. Every session where they had to ask "where is X?" was wasted time.

Operational > architectural. Users ask "why isn't prod scraping?" more than "explain the extraction pipeline". Firefighting paths matter.

Output

This skill doesn't produce a standalone artifact — it feeds into other skills:

• agents-md — evidence-based Map entries and gotchas
• Any project doc — vocabulary alignment, coverage gaps
• Skill creation — if a concept cluster is big enough, maybe it needs its own skill

Example Session

User: "can you see my past sessions and figure out what concepts I use a lot?"

1. Found 61 sessions in parser-staging
2. Extracted 61 starter messages
3. Built concept frequency (20 clusters)
4. Compared against AGENTS.md Map (16 entries)
5. Found 6 gaps: collage, zones, house_kg, admin, photos, freshness
6. Updated Map with user's vocabulary
7. Result: 73-line AGENTS.md that covers all top-20 concepts