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

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

Documentation Hierarchy

AGENTS.md (entry point)
    │
    ├─ docs/design/ai-agents-instruction.md (instruction system design)
    │
    ├─ docs/standards/ (SSOT for standards)
    │   ├─ task-classification.md (label definitions)
    │   ├─ coding-conventions.md
    │   ├─ security.md
    │   ├─ testing.md
    │   └─ workflow.md
    │
    ├─ docs/guidelines/ (detailed how-to)
    │   ├─ database.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:

```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