theinternetitheinterneti/TTA.dev/.claude/skills/create-atomic-note/SKILL.md

create-atomic-note

Skill0 starsChanged 7 months agoMITView on GitHub

Use this skill when saving a single-topic documentation note to docs/kb-exports/ for later knowledge base ingestion.

In this repository25 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/tta-dev.mdcCursor rule
- build-test-verifySkill
- core-conventionsSkill
- create-pull-requestSkill
- git-commitSkill
- sdd-workflowSkill
- self-review-checklistSkill
- session-startSkill
- build-test-verifySkill
- core-conventionsSkill
- create-agentSkill
- create-atomic-noteSkill
- create-pull-requestSkill
- Feature DevelopmentSkill
- git-commitSkill
- Incident ResponseSkill
- Package ReleaseSkill
- sdd-workflowSkill
- self-review-checklistSkill
- session-startSkill
- ttadev-llmSkill
- ttadev-primitivesSkill

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
After completing any significant task: new feature, bug fix, architectural decision, research finding, or outstanding TODO.
line 14
Distinctive:
YAML frontmatter is mandatory: Every note must include all required fields (see template).
line 21
Very specific:
Always save to: docs/kb-exports/<YYYY-MM-DD_slug>.md
line 110

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Skill: create-atomic-note

Purpose

Save a single-topic documentation note to docs/kb-exports/ for periodic ingestion into the TTA-notes knowledge base.

When to Use

After completing any significant task: new feature, bug fix, architectural decision, research finding, or outstanding TODO.

Rules

One topic per file. Two topics = two files.
Filename: YYYY-MM-DD_<kebab-case-slug>.md
- Example: 2026-03-04_persistence-primitives-design.md
YAML frontmatter is mandatory. Every note must include all required fields (see template).
Length limit: ~300 lines max. If longer, split into multiple notes.
Never write narrative prose for its own sake. Be dense and factual.

Required Frontmatter

---
type: <note-type>
priority: <1|2|3>
status: draft
tags: [tta-dev]
source_agent: claude-code
date: YYYY-MM-DD
related_files: []
---

Field Reference

Field	Values	Notes
`type`	`architecture` `decision` `bug-fix` `feature` `research` `todo`	Pick the closest match
`priority`	`1` `2` `3`	1 = action needed now, 2 = medium, 3 = reference/low
`status`	`draft` `review` `stable`	New notes start as `draft`
`tags`	array	Always include `tta-dev`; add topic tags: `dev-todo` `learning-todo` `ops-todo` `template-todo`
`source_agent`	string	`claude-code`, `cline`, `copilot`, `gemini`, etc.
`date`	`YYYY-MM-DD`	Today's date
`related_files`	array of repo paths	Files this note documents; can be empty

Content Structure

# <Short, Specific Title>

## Summary
One paragraph: what this is and why it matters.

## Context
What led to this? What problem was being solved?

## Decision / Finding
The actual content — be specific and dense.

## Consequences / Next Steps
What does this enable? What should happen next?

Full Example

Filename: 2026-03-04_uow-abstract-base-class-design.md

---
type: architecture
priority: 2
status: draft
tags: [tta-dev, dev-todo]
source_agent: claude-code
date: 2026-03-04
related_files:
  - platform/primitives/src/tta_dev_primitives/persistence/uow.py
  - tests/unit/test_uow.py
---

# Unit of Work: Abstract Base Class Design

## Summary
AbstractUnitOfWork defines the contract for transactional boundaries in TTA.dev
persistence primitives. All concrete UoW implementations (Supabase, in-memory, fake)
inherit from it.

## Context
Needed a standard interface so workflow primitives can swap persistence backends
without changing business logic. Inspired by the Repository + UoW pattern from
Domain-Driven Design.

## Decision / Finding
- `AbstractUnitOfWork` exposes `commit()`, `rollback()`, and `__aenter__`/`__aexit__`
- `FakeUnitOfWork` ships in the testing module for use in unit tests
- No direct Supabase coupling in the abstract class

## Consequences / Next Steps
- Any new persistence backend just implements AbstractUnitOfWork
- TODO: add Dolt backend (see platform/dolt/)

Where to Save

Always save to: docs/kb-exports/<YYYY-MM-DD_slug>.md

The TTA-notes repo ingests this directory periodically. Do not create subdirectories inside kb-exports/.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free