Skip to content

docs, add AI skill knowledge base for h5cpp usage patterns #189

@steven-varga

Description

@steven-varga

Problem

AI coding assistants hallucinate h5cpp usage because the library is niche,
template-heavy, and has non-obvious invariants: include order matters, property
lists have type constraints, and type dispatch goes through traits that are
invisible at the call site. There is no curated, machine-readable corpus of
verified h5cpp patterns for models to draw on.

Goal

A self-maintaining skill knowledge base anchored to the test suite, structured
for injection into all four agents (Claude, Kimi, Codex, Copilot).

Architecture

docs/skills/ — verified example corpus

Structured Markdown files, one per topic, with YAML front-matter:

---
skill: io-write-vector
tags: [io, write, stl, vector]
hdf5_min: 1.10
tested: true   # snippet appears verbatim in a ctest
---

Constraint: every snippet tagged tested: true must appear verbatim in a
ctest. A CI script scripts/verify-skills diffs skill snippets against their
test source and fails on divergence.

docs/skills/index.md — tag index

Maps tags → skill files for agent retrieval.

scripts/mem integration

Skill files imported into knowledge.db as observations on a h5cpp-skills
entity. mem-consolidate re-imports on each daily run.

Scope (this issue — core I/O patterns)

  • docs/skills/index.md
  • docs/skills/includes.md — entry points and include order
  • docs/skills/io-create.mdh5::create dataset and file patterns
  • docs/skills/io-write.mdh5::write full and partial
  • docs/skills/io-read.mdh5::read full and partial
  • docs/skills/io-append.mdh5::append / packet table streaming
  • docs/skills/properties.md — property list composition with operator|
  • scripts/verify-skills — CI verification stub

Out of scope (follow-on issues)

  • Compound type / struct patterns
  • Attribute I/O patterns
  • Linalg adapter patterns (Armadillo, Eigen, xtensor, …)
  • MPI collective / independent patterns
  • S3 / ROS3 patterns (covered in feature, add HDF5 S3 / ROS3 VFD support #188)
  • Fine-tuning dataset generation

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions