docs-update

Documentation Update Workflow

Workflow for documentation changes with SSOT awareness.

Prerequisites

• Use git-workflow Skill for branch, commit, and PR workflow.
• Understand SSOT structure before editing any documentation.

SSOT Awareness

Critical: Before editing documentation, identify if the file is an SSOT or references one.

SSOT Locations

Category	SSOT Location	Description
Agent behavior	AGENTS.md	Entry point for all agents
Agent instruction design	docs/ai/design.md	Command/Skill/Rule architecture
Label definitions	docs/guidelines/task-classification.md	All label types and meanings
Label → Skill mapping	.claude/skills/label-context-mapping/	Operational routing
Coding conventions	docs/guidelines/coding-conventions.md	Code style rules
Security rules	docs/guidelines/security.md	Security requirements
Testing standards	docs/guidelines/testing.md	Test requirements
Workflow	docs/guidelines/workflow.md	Development workflow

SSOT Rules

1. If editing an SSOT file: Update carefully, as other files reference it
2. If editing a non-SSOT file: Ensure it references the SSOT, don't duplicate information
3. If information conflicts: The SSOT is authoritative; update the referencing file

Applicable Files

Path	Type	Description
AGENTS.md	SSOT	Agent behavior entry point
ARCHITECTURE.md	SSOT	System architecture
docs/guidelines/	SSOT	Project guidelines and standards
docs/design/	Reference	Design documents
docs/chains/	Reference	Chain-specific documentation
docs/ai/task-contexts/	Context	Task-specific procedures
internal/AGENTS.md	Scoped SSOT	Internal package guidelines
pkg/AGENTS.md	Scoped SSOT	Public package guidelines

Documentation Hierarchy

AGENTS.md (entry point)
    │
    ├─ docs/ai/design.md (instruction system design)
    │
    ├─ docs/guidelines/ (guidelines and standards)
    │   ├─ task-classification.md (label definitions, SSOT)
    │   ├─ coding-conventions.md
    │   ├─ security.md
    │   ├─ testing.md
    │   ├─ workflow.md
    │   ├─ architecture.md
    │   ├─ code-generation.md
    │   └─ ...
    │
    └─ docs/ai/task-contexts/ (task-specific context)
        ├─ bug-fix.md, feature-add.md, etc.
        └─ chains/ (chain-specific)

Workflow

1. Identify Document Type

Before editing, determine:

• Is this file an SSOT?
• Does this file reference an SSOT?
• What other files might be affected?

2. Check for Duplicated Information

If the information you're adding already exists elsewhere:

• Find the SSOT location
• Add a reference instead of duplicating

3. Make Changes

Follow markdown style guidelines:

• Use ATX-style headers (#, ##, ###)
• One blank line between sections
• Code blocks with language specifier
• Tables for structured data
• Relative links within docs

4. Verify Cross-References

After changes:

• Links work correctly
• SSOT references are accurate
• No information duplication
• Consistent formatting

Markdown Style

Headers

# Top Level (document title)

## Section

### Subsection

Code Blocks

Always specify language:

```go
func example() {}
```

make go-lint

### Tables

Use tables for structured data:

```markdown
| Column 1 | Column 2 |
|----------|----------|
| Value 1  | Value 2  |

Links

• Use relative links: [link](../path/to/file.md)
• Verify links work after moving files
• Update cross-references when renaming

Self-Review Checklist

• SSOT location identified (if applicable)
• No duplicated information
• References point to correct SSOT
• Markdown renders correctly
• Links work
• Consistent formatting
• Tables align properly

Commit & PR

Use git-workflow skill for commits:

• Commit type: docs
• Scope: Optional (or target area: btc, eth, standards, etc.)

Example: docs(standards): update coding conventions for error handling

Related

• git-workflow - Branch, commit, PR workflow
• AGENTS.md - Agent entry point
• AI Agent Instruction Design - System design
• Task Classification - Label SSOT