STD-019: Discoveries Lifecycle

The Discoveries system captures micro-learnings during daily work — the small insights that are too small for Codex entries but too valuable to lose. Three categories organize entries by nature: tools, system, workflow. Entries are append-only; old entries are never edited. An explicit graduation rule promotes frequently-referenced discoveries to Codex or Pattern Journal, but this rule has no automated enforcement — it depends on author discipline during review.

Principles

  1. Append-only. Entries are never modified after creation. If an earlier entry was wrong, add a new entry with the correction and a back-reference. The original stays as a historical record of understanding at that point in time.

  2. Micro-scope. Each discovery captures one insight: a flag, a behavior, a workaround, a mental model shift. If the entry exceeds ~15 lines, it belongs in Codex or a worklog session, not Discoveries.

  3. Traceable to context. Every entry links back to the worklog where it was first encountered. Without the worklog reference, the discovery loses its situational context — why it mattered on that day.

  4. Graduation is a promotion, not a deletion. When a discovery earns Codex or Pattern Journal status, the original entry remains with a graduation note. The Discoveries log is a complete timeline of learning, never pruned.

Entry Template

Every discovery entry MUST follow this structure:

=== YYYY-MM-DD: Title of Discovery

Description of what was learned, why it matters, and the context
in which it was discovered.

 [source,bash]
 ----
 # Optional: command or code that demonstrates the discovery
 example-command --with-flags
 ----

**Worklog:** xref:YYYY/MM/WRKLOG-YYYY-MM-DD.adoc[WRKLOG-YYYY-MM-DD]

Between entries, a horizontal rule separates them:

=== 2026-04-01: Discovery A

Content...

**Worklog:** xref:2026/04/WRKLOG-2026-04-01.adoc[WRKLOG-2026-04-01]

'''

=== 2026-04-03: Discovery B

Content...

**Worklog:** xref:2026/04/WRKLOG-2026-04-03.adoc[WRKLOG-2026-04-03]

Categories

Category Scope Directory

Tools

CLI commands, flags, tool behaviors, editor tricks, git patterns

partials/discoveries/tools/

System

OS behavior, kernel, filesystem, networking, hardware quirks, package management

partials/discoveries/system/

Workflow

Process insights, automation patterns, documentation habits, productivity techniques

partials/discoveries/workflow/

File Organization

partials/discoveries/
├── _index.adoc             # Master index — all discoveries by date
├── tools/
│   └── tools.adoc          # Append-only tools discoveries
├── system/
│   └── system.adoc         # Append-only system discoveries
└── workflow/
    └── workflow.adoc        # Append-only workflow discoveries

pages/discoveries/
├── index.adoc              # Includes _index.adoc partial
├── tools.adoc              # Includes tools partial
├── system.adoc             # Includes system partial
└── workflow.adoc           # Includes workflow partial

Master Index

The master index (partials/discoveries/_index.adoc) lists all discoveries in reverse chronological order with category tags:

[cols="1,2,1"]
|===
| Date | Discovery | Category

| 2026-04-06
| xref:discoveries/tools.adoc#_2026-04-06-title[Title]
| Tools

| 2026-04-03
| xref:discoveries/workflow.adoc#_2026-04-03-title[Title]
| Workflow
|===

When adding a new discovery: append the entry to the category partial, then add a row to the master index.

Graduation Workflow

Graduation promotes a discovery that has proven its value through repeated use. The threshold is explicit: three or more references to the same discovery across worklogs, sessions, or other documents.

Step-by-Step

  1. Identify the candidate. During worklog review or monthly summary, notice a discovery referenced 3+ times.

  2. Determine destination.

    • If the discovery is a reference pattern (command syntax, flag combinations, reusable snippet) — promote to Codex.

    • If the discovery is experiential wisdom (process insight, mental model, workflow technique) — promote to Pattern Journal.

  3. Create the Codex or Pattern Journal entry. Write the full entry in the destination, following that system’s standards.

  4. Annotate the original discovery. Append (never replace) a graduation note to the discovery entry:

    [NOTE]
====
Graduated to xref:codex/cli/awk-field-extraction.adoc[Codex: awk Field Extraction] on 2026-04-06.
====

  5. Update the master index. Add a "Graduated" note in the discovery’s row.

  6. Cross-reference from the destination. The new Codex or Pattern Journal entry should reference the original discovery as its origin.

Graduation Decision Table

Signal Destination Example

Same command/flag referenced 3+ times

Codex

awk NR==X pattern used across 4 worklogs

Same workflow insight applied in 3+ contexts

Pattern Journal

"Verify-before, change, verify-after" applied to SSH, DNS, firewall

Discovery spawned a reusable script

Codex (examples directory)

One-liner grew into a function in ~/.local/bin/

New Category Creation

Adding a fourth (or subsequent) category requires:

  1. Create the partial directory: partials/discoveries/<category>/

  2. Create the category partial: partials/discoveries/<category>/<category>.adoc

  3. Create the container page: pages/discoveries/<category>.adoc

  4. Update the master index (partials/discoveries/_index.adoc) to include the new category

  5. Update the nav file to add the new category page

  6. Build check: make 2>&1 | grep -E "WARN|ERROR"

Compliance

Check Method Pass Criterion

Entry has date-titled heading

grep -c '^=== [0-9]{4}-' partials/discoveries/*/.adoc

Every entry matches === YYYY-MM-DD: pattern

Entry has worklog reference

grep -c 'Worklog:' partials/discoveries/*/.adoc

Count matches entry count

Entries separated by horizontal rules

Visual inspection of category partials

''' between every pair of entries

Master index current

Compare entry count in partials vs rows in _index.adoc

Counts match

Graduation candidates identified

Search worklogs for repeated discovery references

Any discovery referenced 3+ times has graduation note or is queued

Build clean

make 2>&1 | grep -E 'WARN|ERROR'

Zero output

Related