phira-ai Use this skill when writing or updating .archive/**.
Directory layout (canonical)
.archive/records/: per-record files (canonical source of truth).archive/pointers/: pointer files ("since last record" state).archive/graph.dot: derived Graphviz/DOT (committed)
Record file format
- Each record is a Markdown file with:
- YAML front matter between
---lines - a short Markdown body
- YAML front matter between
- Records must be:
- human readable
- machine parseable
- stable over time (avoid ephemeral noise)
Record ID and filename
- Filename:
<record_id>.md record_idrequirements:- ASCII only:
[a-z0-9][a-z0-9-]* - stable (never reuse an ID)
- recommended pattern:
r-YYYYMMDD-<slug>
- ASCII only:
YAML front matter schema (minimum)
Required keys
id: string, equals filename without.mdschema_version: number, current:1type: one of:Design(ideas/specs/reading/plans/pseudocode)Build(implementation/integration/refactors/infrastructure changes)Evaluate(tests/benchmarks/experiments + analysis)Decide(normative decisions: adopt/reject/pivot/change defaults)
title: short human labelparents: list of record IDs (lineage). Use[]only for the initial root record.
Strongly recommended keys
status: short outcome/valence (prefer a small, consistent set)- suggested by type:
- Design:
proposed,active,archived - Build:
in_progress,done,reverted - Evaluate:
positive,negative,inconclusive - Decide:
adopted,rejected,superseded
- Design:
- suggested by type:
tags: list of short tagscreated_at: ISO-8601 timestamp (e.g.2026-02-28T18:10:00Z)git(when applicable):branch: stringhead: string (commit sha)range: string (e.g.<base>..<head>)stash: string (e.g.stash@{0})
edges: list of typed links to other records (semantic links; not lineage)- item schema:
{ type: <edge_type>, to: <record_id>, note: <optional> } - suggested
edge_type:implements,tests,evaluates,supports,refines,refutes,depends_on,supersedes,produces,parallels
- item schema:
Optional keys
links: list of external references- item schema:
{ kind: <kind>, ref: <string>, note: <optional> } - kinds:
url,doi,arxiv,issue,pr,paper
- item schema:
artifacts: list of repo-local artifacts- item schema:
{ path: <repo-relative path>, note: <optional> }
- item schema:
metrics: list of structured metrics (primarily forEvaluate)- item schema:
{ name: <string>, value: <number|string>, split: <optional>, unit: <optional>, direction: <optional>, baseline: <optional>, note: <optional> } directionsuggestions:higher_better,lower_better,target
- item schema:
time: optional structured timing- schema:
{ started_at: <optional ISO-8601>, ended_at: <optional ISO-8601> }
- schema:
opencode: optional provenance (when git is missing or insufficient)- schema:
{ session_id: <string>, message_id: <optional string>, note: <optional string> }
- schema:
Markdown body conventions (keep it short)
Preferred sections by record type
- Design:
## Intent,## Spec,## Open questions,## Next - Build:
## Intent,## What changed,## Notes,## Next - Evaluate:
## Intent,## Setup,## Command,## Metrics,## Outcome,## Notes - Decide:
## Decision,## Rationale,## Consequences,## Alternatives considered
Writing rules
- Prefer bullets.
- Avoid pasting long diffs or raw logs.
- Do not include secrets.
- If you infer something, label it as inference and attach evidence.
- For any non-trivial claim (especially in
## Outcome/## Root cause/## Decision), include at least one evidence hook:- git ref/range, command, config path, artifact path, or a link.
Lineage vs semantic links
- Use
parentsto encode provenance/derivation (the DAG spine). Do not useparentsfor mere chronology. - Avoid adding
edgesthat simply duplicate whatparentsalready expresses. - The DAG visualization uses only lineage edges; semantic
edgesare not rendered as separate arrows (they may be used as hints for edge labels). - Prefer keeping the graph clean:
- For
Build: parent theDesignplan it implements. - For
Evaluate: parent theBuildorDesignrecord it evaluates. - For
Decide: parent the evidence records used to decide (typicallyEvaluatenodes). - For reruns/corrections: parent the record being corrected.
- For
Guidance by type
Decide:- evidence should primarily be listed in
parents. - avoid
edges: supportsback to those same parents unless you need a non-lineage cross-link.
- evidence should primarily be listed in
Evaluate:- if you include a
Commandblock, keep it exact (copy/paste). - if the command is unknown, say so explicitly.
- prefer expressing the evaluation target via
parents; avoid adding an extraedgeslink unless it is a non-lineage cross-link.
- if you include a
Build:- never include placeholder file paths in
applymode; omit or ask for the exact paths.
- never include placeholder file paths in
Minimal templates
Decide
id: r-YYYYMMDD-slug schema_version: 1 type: Decide title: "..." parents: [r-...] status: adopted tags: [topic] git: branch: "..." head: "..." edges:
- type: supports to: r-...
Decision
- ...
Rationale
- ...
Evaluate
id: r-YYYYMMDD-slug schema_version: 1 type: Evaluate title: "..." parents: [r-...] status: inconclusive tags: [topic] git: branch: "..." head: "..." range: "..." metrics:
- name: "..." value: 0
Command
<copy-paste command>
Outcome
- ...