Pitfalls (Wrong vs Right)

This document lists common failure modes and the correct patterns to follow.

1. Storing long-term knowledge only in workdocs

• •Wrong: Keep important, reusable decisions only inside workdocs, so future sessions cannot reliably discover them.
• •Right: Promote stable, reusable conclusions into the relevant skill package under /.system/skills/ssot/**, and leave workdocs as scenario-local execution state.
• •Related: /.system/skills/ssot/repo/skill-developer/skills-overview/SKILL.md

2. Putting AI behavior rules in README

• •Wrong: Encode AI constraints and safety rules in README.md where they are ambiguous and easily duplicated.
• •Right: Put strategy/boundaries in AGENTS.md, and put reusable SSOT reference content in /.system/skills/ssot/** supporting docs.
• •Related: /.system/guides/DOCS_CONVENTION.md

3. Editing tool-owned marker blocks by hand

• •Wrong: Manually edit content inside tool-owned regions (for example the <!-- BEGIN/END ABILITY_INDEX --> blocks).
• •Right: Edit the authoritative inputs (ability registries / SSOT skills) and regenerate via tooling when available.
• •Related: /.system/skills/ssot/repo/documentation-conventions/documentation/conventions/machine_writable_entrypoints.md

4. Breaking skill identity casually

• •Wrong: Rename a skill directory without keeping SKILL.md name in sync (or without updating references and wrappers).
• •Right: Treat a skill directory name + SKILL.md name as the stable identity; keep them aligned and regenerate wrappers.
• •Related: python scripts/devops/skills/sync_skills.py --check --target repo --publish-set repo_minimal

5. Missing required front matter on SKILL.md

• •Wrong: Create or edit a skill SSOT entrypoint without valid name and description front matter.
• •Right: Keep SKILL.md front matter valid and regenerate provider wrappers via tooling.
• •Related: /.system/skills/ssot/repo/skill-developer/skills-overview/SKILL.md

6. Breaking boundaries across scopes

• •Wrong: Make cross-module changes from inside a single module directory without coordination, or modify system registries without following strategy.
• •Right: Use integration scenarios for cross-module work, follow the closest applicable AGENTS.md, and record decisions in workdocs.
• •Related: /.system/skills/ssot/repo/architecture-core-mechanisms/module-workflow/SKILL.md

7. Leaking unstable internal references into SSOT

• •Wrong: Reference unstable, tool-internal, or build-stage documentation paths from SSOT docs.
• •Right: In SSOT, only link to stable repository paths intended for long-term use (especially /.system/skills/ssot/** and relevant /.system/** guides).
• •Related: /.system/guides/DOCS_CONVENTION.md