Maintain curated indexes

Type: types/instruction.md

Audit curated tag READMEs (kb/tags/<tag>-README.md, type tag-readme) for editorial quality, completeness, and coherence. A tag README is the tag's curated head: a hand-written editorial body with groupings and context phrases, small by type contract (weight gates). The complete per-tag listing is not committed — it is generated at ProperDocs build time for the published site (ADR 025); agents reconstruct it on demand with the scoped rg recipe below.

This instruction is also the route for fixing validator warnings on tag-READMEs (weight gate, complete one-hop reach). The mark's maintenance rules — when to declare or drop complete, the lifecycle exits, the smells — live in the tag-readme type spec; read it before changing a mark.

When to use

  • During periodic KB hygiene
  • After a batch of new notes have been added to a tag
  • When navigating an index feels disoriented — too many entries, unclear groupings, missing context

Steps

1. Inventory tags and sizes

rg -N --no-heading '^tags:' kb/notes/ kb/reference/ kb/instructions/ kb/agent-memory-systems/ kb/agentic-systems/ --glob '*.md' \
  | grep -o '\[.*\]' | tr -d '[]' | tr ',' '\n' | sed 's/^ *//' \
  | sort | uniq -c | sort -rn

This shows how many artifacts each tag has across the participating collections listed in kb/tags/COLLECTION.md. Every tag in use needs a head; validation reports a tag with no head at kb/tags/<tag>-README.md, and the fix is to write the head or drop the tag. Indexes that haven't been updated after significant tag growth may need revision.

2. For each curated index, evaluate editorial quality

Load the index and list the tag's full membership:

rg -l '^tags:.*\bTAG\b' kb/notes/ kb/reference/ kb/instructions/ kb/agent-memory-systems/ kb/agentic-systems/ --glob '*.md' \
  | xargs -r rg -N --no-heading '^description:\s*' -r ''

Ask:

  • Can a writer decide placement from the opening? It must state what an artifact must substantively address to qualify and distinguish confusing neighboring tags. Mention or background use is insufficient. Check a clear member and a nearby non-member against the wording; when both tags fit, allow both. Curated background links do not themselves assert membership.
  • Do the groupings still make sense? Sections should reflect natural clusters. If a section has grown to 15+ entries, it may need sub-grouping or splitting into its own index.
  • Are the context phrases still accurate? A note's role in the topic may have shifted since the phrase was written.
  • Are important notes missing? Compare the curated entries against the tag's full membership from the listing above. Tagged notes absent from the index are either: (a) not important enough to curate, which is fine, or (b) missing editorial placement, which should be fixed.
  • Are there entries that no longer belong? A curated entry whose note has drifted away from the topic should be removed (the note stays reachable through the build-time listing and the scoped query).

3. Check for orphaned notes

# Notes with no tags field at all
rg -L "^tags:" kb/notes/*.md

For each orphan, consider whether adding tags would help future readers find it. Read each candidate head and assign the tag only when the note meets its inclusion condition. Clarify an ambiguous condition before assigning.

4. Split or promote

When a tag grows large and internal clusters emerge:

  1. Look at the curated groupings — these often reveal natural sub-tags.
  2. Create kb/tags/<tag>-README.md with a description and type: types/tag-readme.md (template in the type spec); the filename names the tag.
  3. Add the new tag to relevant notes' tags: field — keeping the parent tag on every note (never a partial migration; see the split discipline in the tag-readme type spec).
  4. Write the curated body for the new README; the complete listing appears on the published site automatically.

Split criteria: - Would the resulting indexes each have 5+ notes? - Do the clusters represent genuinely distinct topics, or just editorial convenience?

5. Update the tags hub

Add a new head to kb/tags/README.md, the hub readers use to browse by tag. It is an ordinary collection landing with no completeness mark, so nothing checks that it lists every head.

6. Validate the tag collection

Run commonplace-validate kb/tags. Marks range over every participating collection, so a clean validation of one collection does not clear a head.

Principles

  • The curated index is editorial, not exhaustive — it's a "best of" selection with context, not a complete listing.
  • Completeness is handled elsewhere — the build-time site listing for humans, the scoped rg query for agents. Don't chase complete coverage in the curated body unless a note is genuinely important for the topic's story.
  • Groupings serve readers, not taxonomy — optimize for "does this help someone understand the topic?" not "is this logically clean?"