Doc Conventions

Documentation Conventions

File standards

• Last updated date at the top of every document (format: YYYY-MM-DD or last updated: YYYY-MM-DD).
• Lowercase filenames with underscores. No spaces, no camelCase. Example: design_decisions.md, not DesignDecisions.md.
• Organize into subfolders by topic rather than flat directories.

Content standards

• Document research, design decisions, alternatives considered, and the "why".
• Don't just describe what was built. Explain why it was built that way and what else was considered.
• Keep docs close to the code they describe.

Internal documentation

Use ./internal/ for documentation that isn't meant to be shared (design notes, debugging logs, scratch work). This directory should be in .gitignore.

Session logs

Daily session logs go in ./internal/log/log_YYYY-MM-DD.md. These capture what was done, decisions made, and open questions. Useful for continuity across sessions.

Dependency change tracking

When a session adds, removes, or bumps package versions, include a dependency changes section in the session log. This is the only place dependency changes are recorded outside the source-of-truth files (pyproject.toml, package.json, uv.lock, bun.lock).

Format

## Dependency changes

| Action | Package | Old | New | Type |
|--------|---------|-----|-----|------|
| added | httpx | -- | 0.27.2 | direct |
| bumped | orjson | 3.10.0 | 3.10.5 | direct |
| removed | requests | 2.31.0 | -- | direct |

How to generate

• Python: git diff pyproject.toml for direct deps, git diff uv.lock for transitives
• JavaScript: git diff package.json for direct deps
• If many transitive changes, summarize with count: "12 transitive dependencies updated (see uv.lock diff)"

What NOT to do

• Do NOT create a deps.md, dependencies.json, or any separate manifest
• Do NOT dump full uv tree or bun pm ls output -- only report changes
• The source of truth is always pyproject.toml / package.json / lock files

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fblissjr
• Source: fblissjr/fb-claude-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.