felt

felt — Working with Fibers

Fibers are concerns (tasks, decisions, questions, specs) stored as directory-contained markdown. Their relationships come from three surfaces: containment by path, [[wikilinks]] in the body for narrative connection, and structured frontmatter (inputs.from) for computational provenance. Structured frontmatter — decisions with excluded alternatives, inputs and outputs with recipes, insights backed by evidence — accretes as the work becomes computationally concrete. felt carries these fields as part of the fiber substrate; the structure is yours to shape.

For literature audits, model the audited paper statement as the claim and anchor the supporting evidence in the cited source itself with a traceable selector such as a quote, figure, or table. Use audit reports as artifact evidence for your own findings about the audit process, not as substitutes for literature evidence.

Proactive formalization. Retroactive extraction. Consolidation over time. Coherence when needed.

---

CLI

Something came into focus. Start:
    felt add <slug> "name" -t tag -o "one-line outcome"

Understanding crystallized. Accrete:
    felt edit <id> --status active
    felt edit <id> --tag X
    felt edit <id> --decision cov --label "Covariance" --option 'glass:GLASS mocks'
    felt edit <id> --input 'catalog:data:build-mocks.galaxy-catalog'    # id:type:source.output
    felt edit <id> --insight 'stability:Posterior is stable under jackknife'
    Read then Edit .felt/<path>/<slug>.md                               # body, wikilinks, deeper frontmatter

Search and read:
    felt ls                                              # tracked (open and active)
    felt ls "query" [-t tag] [-s closed]                 # any filter widens to all statuses
    felt ls --body "query"                               # FTS5 body search
    felt tree [<id>]                                     # containment hierarchy
    felt show <id>                                       # full
    felt show <id> -d summary | -d compact               # metadata + lede | + frontmatter counts
    felt show <id> --body                                # body with start line
    felt show <id> --decisions|--inputs|--insights       # targeted frontmatter slices
    felt show <id> --citations|--consumers               # narrative back-refs | data-flow consumers
    felt show <id> --field <key>                         # one frontmatter key, shell-friendly

A thread resolved. Close:
    felt edit <id> --status closed --outcome "what was learned"

History (per-fiber append-only event log):
    felt history <id>                                    # editorial chain (newest first)
    felt history <id> --last 1                           # what the previous session left
    felt history <id> --mechanical                       # + add/edit/rm/external_edit
    felt history <id> --kind <type>                      # filter to typed editorial events (e.g. review-comment)
    felt history append <id> --summary "..."             # log session continuity
    felt history append <id> --kind review-comment --summary "..."   # typed event for downstream tools

Reshape:
    felt nest <child> <parent>                           # move a fiber subtree under another
    felt unnest <id>                                     # promote a nested fiber to the top level

Maintain:
    felt check                                           # broken refs, frontmatter issues
    felt migrate [--dry-run]                             # normalize legacy layout

Statuses: · untracked, ○ open, ◐ active, ● closed Detail: name < compact < summary < full. Summary shows the lede (first paragraph of the body; write it to stand alone). Relationships: directory containment, [[wikilinks]] in bodies, inputs.from for data flow. Nested IDs use paths (bao-analysis/damping-prior).

Outcomes longer than a sentence: edit .felt/<path>/<slug>.md directly using a |- block scalar (outcome: |-). felt edit -o "…" shell-escapes quotes and mangles multiline content; block scalar takes content literally so paragraphs, lists, and image embeds round-trip cleanly.

---

Philosophy

Formalize while working. The moment to accrete structure is right after you respond, while the user reads; that time is unbilled, and what crystallized during the exchange is still fresh. Write inputs while scripts run, record excluded options the moment you reject them, file what just came into focus. Formalization belongs in the flow of the work, not in a separate pass at the end.

Follow the understanding. Don't ask permission to file. The user's corrections and opinions are the primary trigger; when the direction of the conversation shifts, your fibers shift with it, reversals included. You are tracking what has come to matter, not what was said first.

Help the user think. When the conversation has careful-thinking character — deciding something non-trivial, scoping a sub-analysis, drafting a spec, talking through an open question — lean on the crafting rhythm from crafting.md (two diamonds, six stances, funnel ledger, qualitative self-check) to help the user converge. Err toward using it; the failure mode is letting important decisions slide by without structure, not pressing too hard.

Extract what slipped through. Continuous formalization catches most things. At session end, mine decisions, patterns, and findings that weren't captured in the moment; this is a backstop, not the primary mode.

Outcomes teach. An outcome that says "done" or "investigated X" has failed. Put the conclusion in: what was learned, what was decided, why. Someone reading the outcome should learn the thing without opening the body. For outcomes longer than a sentence, use |- block scalar form via direct file edit (not felt edit -o "...").

Consolidate over time. Quick fibers become noise. Read the assemblage periodically and compost stale fibers into doc fibers, fix coherence across siblings, reshape branching. See maintenance.md.

CLAUDE.md stays lean. Commands, paths, context pointers. Documentation fibers carry the depth.

Propagate decisions. A decision rarely touches one place. Use Explore agents to find consequences in config, code, methodology, and other fibers. Record the consequence in code or fibers, and add wikilinks where the narrative connection matters.

---

What to Extract

Quick fibers

Category	What to capture
Decision	Choice made, alternatives, reasoning. Include "decided NOT to."
Question answered	What was figured out. Mechanism, cause, how.
Pattern	Architectural insight, convention, workflow.
Finding	What was built, measured, produced.

Documentation fibers

Category	What to capture
Reference doc	Accumulated understanding. Architecture, philosophy, decision trees.
How-to	Procedures that get reused. More depth than CLAUDE.md.

Tool-owned frontmatter

Fibers may carry tool-owned frontmatter namespaces — top-level keys felt doesn't parse but stores and displays as part of the fiber substrate. When a tool namespace is part of the work, edit it carefully in the fiber file and keep the ordinary felt surfaces current alongside it: outcome for latest state, felt history for chronological handoff, sub-fibers for durable findings. The tool that owns the namespace owns its semantics; felt only round-trips the bytes.

CLAUDE.md updates

• Commands and invocations
• Context pointers (paths, important fibers, documentation fibers)
• Workflow sequences

---

Quality Standards

Red flags:

• Generic summaries instead of specific findings
• "We discussed X" without capturing what was concluded
• Closing fibers without substantive outcomes
• Orphan fibers with no containment context, no [[wikilinks]], and no data-flow connection
• Stale documentation fibers

Good extraction:

• Specific, searchable names (2-3 words)
• Full context in outcome
• Narrative/data-flow links where they carry meaning
• Documentation fibers created when patterns recur

---

Core Rules

• Outcomes teach. One-sentence conclusions that stand alone: they appear in felt ls and -d compact.
• Use the right relationship surface. Nest for containment, [[wikilinks]] for narrative, inputs.from for computational provenance only.
• Compose upward. When closing, ask whether the lesson belongs in a doc fiber or the root fiber; consolidate breadcrumbs.
• Names are concise labels. Body and outcome carry the content.

---

References

Read the reference that matches the situation. Everything above applies always; references go deeper for specific activities.

When	Reference
Accreting structure on a fiber — tier ladder, common shapes, body vs frontmatter	formalization.md
Helping the user think carefully — two diamonds, six stances, funnel, qualitative self-check	crafting.md
Drafting a constitution — pointers not snapshots, desired state, launch	constitute.md
At the end of a session — extracting what slipped through	mining.md
Processing an external transcript — meeting notes, voice note, dictation file	transcripts.md
Reading across the assemblage for mess — composting, coherence, reshaping	maintenance.md
Migrating legacy flat fibers to directory format	migration.md