Writing conventions for kb/agentic-system-analyses/

Type: types/collection-contract.md

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 code's, not a worker's.

Placement and types

state/ holds working analyses. retained/ holds the current accepted analysis of each source, one directory per source. GitHub publications use lowercase <owner>--<project> directory names, preserving repository punctuation. Other sources retain their existing directory naming. Publication names are independent of immutable run IDs. 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/theory/; 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. The workflow's advisory trace audit saves snapshots under state/<run-id>/audit/; these are local evidence, not published artifact members or acceptance judgments. Extract useful evidence before worktree removal, or record the operator's decision that none needs retention. 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/theory/: 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.