Skip to content

Add AX setup: contexts, ADRs, and grill-with-docs skill#428

Merged
brickbots merged 2 commits into
mainfrom
ax_setup
May 22, 2026
Merged

Add AX setup: contexts, ADRs, and grill-with-docs skill#428
brickbots merged 2 commits into
mainfrom
ax_setup

Conversation

@brickbots
Copy link
Copy Markdown
Owner

@brickbots brickbots commented May 22, 2026

Summary

Establishes a bounded-context vocabulary for the Catalog, Positioning, and SQM subsystems so future work shares the same language. Produced via a grill-with-docs session over the existing docs/ax/*.md draft glossaries.

  • CONTEXT-MAP.md indexes the three contexts and how they relate.
  • docs/ax/<area>/CONTEXT.md — canonical glossary per area, with flagged ambiguities and an example dialogue. Companion architecture deep-dives live as docs/ax/<area>.md.
  • docs/adr/0001-positioning-vocabulary.md — locks in the pointing.<axis>.<state>.<RA|Dec|Roll> shape, the choice of aligned over scope, and target_pixel as the (Y, X) image-space coordinate. The code rename will land against the proposal dataclasses in python/PiFinder/types/positioning.py.
  • docs/adr/0002-sqm-published-value-uncorrected.md — captures the intentional choice to publish raw sqm_final rather than the idealised altitude-corrected number.
  • .claude/skills/grill-with-docs/ — the skill that produced the contexts, included so the session can be re-run as the vocabulary evolves.
  • CLAUDE.md — points future agents at the new reference docs.

Key vocabulary decisions baked in:

  • Catalog: enabled (catalog) vs selected (object), sky object vs catalog listing vs CompositeObject, populated vs fully loaded, logged (technical) vs observed (user-facing).
  • Positioning: 2 × 2 matrix pointing.{camera,aligned}.{solve,estimate}; bare "pointing" = pointing.aligned.estimate.
  • SQM: dark sequence (multi-frame wizard concept) vs zero-second sample (single-frame runtime), bias_offsetpedestal, "noise floor" reserved for the published value.

Prototype dataclasses

  • Includes proposed dataclasses to be used for an upcoming refactor as it's the file is referenced in the context. These dataclasses are subject to change in a future refactoring PR

Test plan

  • Skim CONTEXT-MAP.md and confirm relationships are accurate
  • Walk each docs/ax/<area>/CONTEXT.md and confirm terms match how you'd describe them to a new contributor
  • Confirm both ADRs reflect intentional choices, not accidents
  • Verify python/PiFinder/types/positioning.py is the proposal-dataclass file you intended to ship in this PR (it can be split out if not)
  • Check the CLAUDE.md Reference Documentation section is wired to land before Architecture Overview
  • Sanity-check that no unrelated files (gerbers, kicad backups) snuck in

🤖 Generated with Claude Code

brickbots and others added 2 commits May 21, 2026 18:18
Establishes a bounded-context vocabulary for the Catalog, Positioning,
and SQM subsystems so future work shares the same language.

* CONTEXT-MAP.md indexes the three contexts and their relationships.
* docs/ax/<area>/CONTEXT.md gives each area a canonical glossary with
  flagged ambiguities and example dialogue. Companion architecture
  deep-dives live alongside as docs/ax/<area>.md.
* docs/adr/0001 records the Positioning vocabulary (the
  pointing.<axis>.<state>.<RA|Dec|Roll> shape, "aligned" over "scope",
  target_pixel as the (Y, X) coordinate). The pending code rename
  lands against the proposal dataclasses in
  python/PiFinder/types/positioning.py.
* docs/adr/0002 records the intentional choice to publish raw SQM
  (sqm_final) rather than the altitude-corrected value.
* .claude/skills/grill-with-docs/ adds the skill that produced these
  contexts, so the same grilling can be re-run as the vocabulary
  evolves.
* CLAUDE.md points future agents at the new reference docs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@brickbots brickbots merged commit 6c2a7ea into main May 22, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant