What should I do if mental-model.md doesn't exist?

Ask for permission to create it, then scan the codebase and generate a living document that documents end-to-end behavior.

How often should I update the model?

Update it whenever you discover something new from running tests, debugging, or exploring unfamiliar parts of the code.

Who is responsible for maintaining the mental model?

Anyone who touches the codebase should contribute to and maintain this living document, ensuring architecture, data flow, and conventions stay up to date.

mental-model

npx machina-cli add skill automazeio/mental-model-skill/mental-model --openclaw

Files (1)

SKILL.md

1.2 KB

Mental Model

When working on this codebase, first check for mental-model.md in the project root.

If it exists

Read it to understand the codebase architecture, patterns, conventions, and relationships before making changes, when exploring unfamiliar parts of the code, or debugging failed tests or unexpected behavior.

Update it whenever you discover something new — from running tests, hitting unexpected behavior, or exploring unfamiliar parts of the code.

If it doesn't exist

Ask the user if they'd like you to create one. If confirmed:

Create a new file named mental-model.md at the repo root, that builds and maintains a full mental model of the codebase.

Scan the entire codebase and document how the system works end-to-end (architecture, key modules, data flow, relationships, testing approach, Docker/setup, etc).

Treat this as a living document. Update it whenever you learn something new from running tests or hitting unexpected behavior.

Source

git clone https://github.com/automazeio/mental-model-skill/blob/main/mental-model/SKILL.mdView on GitHub

Overview

Maintains a living documentation of the codebase’s architecture, patterns, and relationships. Before making changes, read mental-model.md at the repo root and update it whenever you discover new patterns, behaviors, or test outcomes. If the file doesn’t exist, offer to create it and document end-to-end system behavior.

How This Skill Works

At the project root, check for mental-model.md. If present, read it to understand architecture, patterns, conventions, and relationships before changes or debugging; update it whenever you discover a new pattern or behavior. If it doesn’t exist, propose creating it and, with approval, generate a living document that covers end-to-end system behavior.

When to Use It

Starting a major feature or refactor to understand system structure
Debugging failures or unexpected behavior
Exploring unfamiliar modules or data flows
Onboarding new teammates with architecture context
Documenting lessons learned from tests or new patterns

Quick Start

Step 1: Check repo root for mental-model.md
Step 2: Read it to grasp architecture, patterns, and relationships
Step 3: Update the file with any new findings and commit with a clear message

Best Practices

Check for mental-model.md at the repo root before touching code
Document architecture, data flow, relationships, and conventions clearly
Update the file after running tests or discovering new patterns
Use clear, testable language and keep versions in sync with commits
Review for consistency across modules and keep it living

Example Use Cases

Reading mental-model.md before refactoring module A to understand its interactions
Adding a new service and updating the mental model to include data flow and owners
Encountering a bug and consulting the model to verify intended architecture
Creating mental-model.md when the file is missing for a new project
Onboarding a teammate using the mental model to explain system boundaries

Frequently Asked Questions

Add this skill to your agents