Forge

# Forge Examples

Concrete walkthroughs of the two main forge invocation paths.

## SessionEnd Hook Invocation

**Hook triggers:** `session-end.sh` runs when session ends

**What happens:**
1. Hook calls `ao forge transcript --last-session --queue --quiet`
2. CLI analyzes session transcript for decisions, learnings, failures, patterns
3. CLI writes session ID to `.agents/ao/pending.jsonl` queue
4. Next session start triggers `/forge --promote` to process the queue

**Result:** Session transcript automatically queued for knowledge extraction without user action.

## Manual Transcript Mining

**User says:** `/forge <path>` or "mine this transcript for knowledge"

**What happens:**
1. Agent identifies transcript path or uses `ao forge transcript --last-session`
2. Agent scans transcript for knowledge patterns (decisions, learnings, failures, patterns)
3. Agent scores each extraction by confidence (0.0-1.0)
4. Agent writes candidates to `.agents/forge/YYYY-MM-DD-forge.md`
5. Agent indexes forge output with `ao forge markdown`
6. Agent reports extraction counts and candidate locations

**Result:** Transcript mined for reusable knowledge, candidates ready for human review or 2+ citations promotion.


# Auto-drafted Learnings — F5.4 Feedback Compiler

The `cli/internal/feedbackcompiler` package writes **draft** learning files to
`docs/learnings/` automatically when the verdict ledger records a fail->pass
transition for a directive. These drafts are distinct from forge's
transcript-mined candidates:

| Source | Written to | Status |
|--------|-----------|--------|
| Forge (transcript mining) | `.agents/learnings/` | provisional |
| Feedback compiler (ledger transitions) | `docs/learnings/` | **draft** |

## Promotion rule

Auto-drafted files carry `status: draft` and `directive_id` in their
frontmatter (per ADR-0005 §2.6). A human must review and promote them — the
compiler never auto-promotes. Filename pattern:
`YYYY-MM-DD-auto-<directive-slug>-fail-to-pass.md`.

## Idempotency

If a draft for a transition already exists the compiler skips it. Running the
compiler again after promotion is safe.

## Implementation

- Package: `cli/internal/feedbackcompiler/`
- Reads: `.agents/goals/verdict-ledger.json` (via `cli/internal/verdictledger`)
- Writes: `docs/learnings/YYYY-MM-DD-auto-<slug>-fail-to-pass.md`
- Bead: soc-58nt.5.4


# Executable spec for the /forge skill — transcript→learning capture funnel (BC1 Corpus, loop Move 7 capture).
# /forge mines raw transcripts into CANDIDATE learnings and queues them — it is the funnel,
# not the filter: the promotion ratchet (not forge) decides which survive (one-offs die at
# handoff; repeats promote to .agents/learnings/). It consumes transcripts (raw input), not
# skills, so consumes:[] is correct. Hexagon: domain; produces .agents/research/*.md; shared-
# kernel with standards. (soc-qk4b)

Feature: Forge mines transcripts into candidate learnings
  As the capture funnel of the knowledge flywheel
  I want raw transcripts mined into queued candidate learnings
  So that the ratchet has a stream of candidates to promote or let die

  Scenario: a transcript is mined into queued candidates
    When /forge runs over a session transcript
    Then candidate learnings are extracted and queued for review
    And forge does not itself decide which are durable — it is the funnel, not the filter

  Scenario: promotion is the ratchet's call, applied by --promote
    Given a reviewed candidate worth keeping
    When /forge --promote runs
    Then the learning is written to .agents/learnings/ and its pending source is removed
    And one-offs that were not promoted simply die at handoff (correct)

  Scenario: forge consumes transcripts, not skills
    Then /forge's hexagon consumes no other skill (consumes:[] is correct — it mines raw transcripts)
    And it relates to standards as a shared kernel


# Uncaptured Lesson Patterns

> 30 lessons identified from post-mortem and retro analysis across 14,753 sessions