Fact Writer

Guidance for structuring and maintaining verifiable project fact files. Use this skill when managing FACTS.md, FACTS.mmd, or similar canonical stores.

When to Use

• Creating or updating canonical fact stores (e.g., FACTS.md, FACTS.mmd).
• Documenting verifiable ecosystem properties, constraints, or architectural decisions.
• Resolving state conflicts or contradictions within documentation limits.

When Not to Use

• For writing conversational READMEs or unstructured tutorial documentation (use docs-writer instead).
• When recording temporal, ephemeral state like "Build 45 failed" (fact stores are for persistent architectural truths).
• For writing executable code or scripts.

Common Pitfalls

• Violating Lexical Order: Appending a new fact at the bottom of the list instead of inserting it in strict alphabetical order, breaking the state compression logic.
• Silent Contradictions: Adding a fact that explicitly contradicts an existing node without explicitly removing or updating the old node.
• Prose Injection: Writing long paragraphs of explanation instead of dense, structured nodes.

Core Process

1. Verify State: Read existing fact files entirely before proposing updates; never infer missing state.
2. Contradiction Transparency: Surface conflicts immediately; reject silent overwrites when a proposed fact contradicts an existing A ≠ ¬A state. Replace, do not append.
3. Verifiable Facts Only: Record objective facts grounded in repository configuration, code, and explicit documentation. Zero subjective prose.
4. Structured Format: Enforce rigid hierarchical structures (e.g., Mermaid mindmap or perfectly nested Markdown lists). Group by logical domains like Architecture, Context, Ecosystem.
5. Lexical Sorting: Insert new facts in strict alphabetical order within their domain/level.
   • Case: Case-insensitive (e.g., A and a share same priority; App before apple).
   • Numbers: Natural sort (e.g., v2 < v10).
   • Special Characters: Sort symbols (e.g., @, _) before alphanumeric characters.
6. Reversibility Focus: Offload history, diffs, and rollback logic entirely to Git. Eradicate historical changelogs, sequence IDs, and obsolete states from the fact file itself.

Diagnostics and Revisions

• Contradiction Sweep: Pre-commit self-review to guarantee zero logical conflicts.
• Orphan Pruning: Seamlessly drop redundant, outdated, or superseded facts (e.g., deprecated libraries) to maintain high-density state compression.

What to Avoid

• NEVER insert nodes or lists out of alphabetical order.
• NEVER include conversational prose, narratives, or explanations in fact structures.
• NEVER hallucinate project details. If unsupported by repo state, reject ingestion.
• NEVER preserve historical states when superseded. Replace with the new fact.

Related Skills

• mermaid: You MUST load this skill when creating or maintaining Mermaid.js diagrams.
• mermaid-beta: You MUST load this skill when working with experimental Mermaid.js beta diagrams.