Writing conventions for kb/agentic-system-analyses/

Purpose and quality

This collection holds workflow-produced analyses of external agentic systems, their run state, local types and the analysis method. The operator's primary purpose, supplied on 2026-10-05, is to chart the design space and find solutions useful to Commonplace. A useful public database is secondary. The analysis design brief holds the evaluation priorities for method changes. Analyses support that purpose without including Commonplace adoption advice.

Their contribution is an evidence-grounded account of source-native operation, with bounded synthesis and explicit limitations. The quality goal is fidelity and economy. Explain the external mechanism before applying Commonplace concepts; qualify mappings and keep evidence limits beside claims. The source account must remain intelligible when a reader rejects the mapping.

Authoring

For titled reports, name the system and report role. Use the supplied member type's title and description conventions; worker fragments keep their job's exact headings. State the evidence basis and capture boundary in the member's format; attribution and record formats belong to its supplied contracts.

Analysis workers write only assigned working outputs. Retained analyses are frozen: substantive corrections require a new run. Assembly, acceptance and publication are coordinator tasks.

Placement and types

state/ holds working analyses. retained/ holds the current accepted analysis of each system, one directory per system. retained-archive/ holds superseded analyses. instructions/ holds the analysis method. Comparative writing belongs in kb/agentic-systems/; current Commonplace transfer advice belongs in its separately commissioned transfer scan. Neither belongs in an analysis. Transferable KB theory belongs in kb/notes/; raw source captures belong in source snapshot storage.

Run evidence

An audit that extracts evidence from an analysis run records run-id, method-commit and source-revision under those exact keys. The worktree path is local context, not the run identity. Retain failed worktrees as evidence; the routine removal rule in the analysis skill excludes them.

Use global types under types/ or local types under agentic-system-analyses/types/. Frontmatter-free Markdown is text. Method authors follow method maintenance before editing local types or instructions. Analysts do not load it.

  • kb/sources/: cite tracked ingests, never snapshots; evidenced-by.
  • External: cite evidence used, preferably version-pinned; do not prospect the open web; evidenced-by.
  • kb/notes/: cite theory used in a mapping; rests-on, defined-in.
  • Within this collection: point to supporting members or records; see-also.
  • Local instructions and types: link their governing contracts; composition, see-also.