capture

Files (2)

• HTML-DRAFT.md
• SKILL.md

SKILL.md (first lines)

# Capture

## Invariant

Open an HTML approval draft before every KB write. Apply only the exact writes the
user explicitly approves from the latest draft.

The KB is canonical. Use its live provider connector and schema; keep personal and
provider-specific bindings out of this skill.

## Semantic Interface Requests

Automation callers use the shared package at
`<harness-skill-root>/knowledge-system-interface/v1/`. Resolve it relative to this
skill's harness root; a missing or incompatible package blocks only the dependent
capability and must never trigger a hidden fetch.

Validate `capture-request.schema.json` and its declarative mandate before the normal
loop. Accept only a registered target role within that mandate and semantic meaning,
visibility, evidence, optional Snapshot Token, and rationale. Never accept a
provider write or concrete target location.

Resolve ownership live, deduplicate, and return `blocked` when mandate, ownership,
evidence, freshness, access, or revision prevents a safe proposal. Otherwise return
`drafted` with the same exact ordered operations shown in the HTML approval draft
and validated by `capture-draft.schema.json`.

`drafted` is not authority to write. `applied` requires explicit approval of the
latest exact `/capture` draft and a fresh reread with no drift. Automation and setup
calls never bypass this gate.

## Authoring Rules

Apply three rules to every draft:

1. Keep one canonical owner per meaning; reconcile or link instead of copying.
2. Use the shortest wording that preserves meaning, scope, qualifiers, time, and
   evidence.
3. Make content explicit enough for agents to parse and natural enough for people
   to browse.

Keep these axes independent:

- **Type**: what the page represents; provider-defined, otherwise `Area`, `Project`,
  `Task`, or `Knowledge page`.
- **Ownership**: `Canonical`, `Adapter`, or migration-only `Unresolved`.
- **Maturity**: `Raw`, `Developing`, or `Stable`. New intake starts `Raw`; retained
  knowledge should normally become `Stable`.
- **Kind**: the section's meaning: `State`, `Direction`, `Decision`, `Rule`,
  `Preference`, `Procedure`, `Event`, `Evidence`, `Open item`, `Schema`, `Example`,
  or `Citation`.

Keep one subject per page, one dominant Kind per section, and no empty or decorative
sections. State the current or actionable meaning before history. Keep qualifiers,
rationale, and evidence beside the claim they affect.

Choose Type from the page's primary purpose, not body length or durable prose. An
Area, Project, or Task may contain typed knowledge sections without becoming a
Knowledge page. Do not infer Type from Ownership, Maturity, Status, Parent, or Kind.
In a mixed provider container, keep operational views focused on Areas, Projects,
Tasks, and migration-unclassified rows; expose Knowledge pages through intentional
knowledge views. Do not duplicate pages for different views. When Parent/Subtasks
contains both work and knowledge, require Type-aware views so knowledge does not
appear as work.

Treat structured-table rows as records when their schema and fields carry the full
meaning. Preserve their cell-like shape: do not add page semantic metadata to Notes
or a blank body, and do not treat a repeated title as duplicate meaning when the
table and hierarchy already disambiguate it. A rich body may require semantic
sections without changing an operational page's Type.

## Loop

### 1. Read The Live KB

Search for the subject, aliases, likely owners, adapters, and nearby examples. Fetch
the target's complete affected section and live schema. Follow only relations needed
to establish ownership, avoid contradiction, or make a deletion safe.

Treat local audits and previous drafts as discovery hints, never as substitutes for
live reads. If the target, a plausible competing owner, or required relation cannot
be read, state the gap. Block the write when the gap could hide duplication,
contradiction, unsupported content, material loss, or unsafe deletion.

Completion: the owner, placement, schema, affected content, and relevant relations
are grounded in current KB reads.

### 2. Distill And Reconcile

Extract durable knowledge only. Discard transcript framing, command noise, and
unsupported claims.

For each retained meaning:

- preserve its subject, scope, qualifiers, uncertainty, time, rationale, and useful
  evidence;
- choose its owner, Maturity, and Kind;
- compare it with current content and linked owners;
- preserve, merge, replace, append, or remove it deliberately;
- rewrite the smallest coherent section that expresses the result.

Append only genuine chronological Events or new peers in an existing set. When
removing content, account for unique meaning, inbound links, its replacement, and
the provider's recovery path. Retain revision evidence through provider history or
the bound evidence surface.

Completion: the proposal is the smallest non-duplicative change that preserves
meaning and recoverable history.

### 3. Draft Exact Writes

Create the HTML artifact described in [HTML-DRAFT.md](HTML-DRAFT.md). Render primary
KB mutations first in application order. Put bound Revision Evidence row writes in
a compact final section; they remain mandatory and execute after all primary
mutations. For each primary write show:

- action, human-readable target, and placement;
- exact current and proposed properties or relations;
- complete final affected section or new page body;

From giacomoguidotto/skills, MIT.

More from giacomoguidotto/skills