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/design/ai-agents-instruction.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

• If editing an SSOT file: Update carefully, as other files reference it

• If editing a non-SSOT file: Ensure it references the SSOT, don't duplicate information

• 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/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/design/ai-agents-instruction.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/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:

func example() {}

make go-lint

Tables

Use tables for structured data:

| 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