update-system-map
Update the System Knowledge Map documentation
When & Why to Use This Skill
This Claude skill automates 'codebase archaeology' to maintain an up-to-date System Knowledge Map. It systematically analyzes technical stacks, data models, and business logic to generate comprehensive, structured documentation that bridges the gap between complex source code and stakeholder understanding.
Use Cases
- Developer Onboarding: Quickly bring new engineers up to speed by providing a fresh, auto-generated map of the system's architecture, core entities, and file structures.
- Documentation Syncing: Automatically update `docs/SYSTEM_KNOWLEDGE_MAP.md` during the development lifecycle to ensure technical documentation never lags behind the actual state of the codebase.
- Stakeholder Reporting: Generate high-level overviews for non-technical managers that translate code-level 'verbs' and 'nouns' into clear business capabilities and entities.
- Audit and Compliance: Conduct thorough investigations of business rules and API surfaces, providing precise file and line references for validation logic and system constraints.
- Technical Debt Assessment: Use the automated reconnaissance phase to identify the current scale of the system, including counts of content types, authors, and API endpoints.
| name | update-system-map |
|---|---|
| description | Update the System Knowledge Map documentation |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash, Task |
Update System Knowledge Map
Perform a codebase archaeology investigation and update docs/SYSTEM_KNOWLEDGE_MAP.md with current system state.
Investigation Plan
Phase 1: Reconnaissance (Tech Stack)
- Read
package.jsonfor dependencies and scripts - Read
nuxt.config.tsfor framework configuration - List
app/directory structure
Phase 2: Data Model Discovery (The Nouns)
- Read
content.config.tsfor collection schemas and content types - Count items in
content/,content/authors/,content/podcasts/ - Identify any new entity types or schema changes
Phase 3: Capabilities Discovery (The Verbs)
- List
app/pages/for route handlers - List
server/api/for API endpoints - Read key pages to understand features
- List
app/composables/for reusable logic
Phase 4: Business Rules
- Grep for validation logic in
content.config.ts - Check for any new business rules in server/api handlers
- Review any constants or config files
Phase 5: Generate Report
Update docs/SYSTEM_KNOWLEDGE_MAP.md with:
# System Knowledge Map
> Auto-generated codebase archaeology report for non-technical stakeholders
> Last updated: [current date]
## 1. High-Level Overview
- What this system does (1-2 sentences)
- Tech stack table
## 2. Core Business Entities (The Nouns)
- Content (with all type variants and key attributes)
- Authors
- Podcasts
- Tweets
- Any new entities
## 3. Key Capabilities (The Verbs)
- Content management features
- Discovery & navigation features
- Visualization features
- Reading experience features
## 4. Business Rules & Logic
- Validation rules with file:line references
- Workflows (e.g., reading status)
- Naming conventions
## 5. Integrations
- External services
- Internal modules
## 6. API Surface
- All endpoints with methods and purposes
## 7. File Structure
- Key directories and their purposes
## 8. Current Scale
- Approximate counts of content, authors, etc.
Important Guidelines
- Be thorough: Read actual files, don't assume
- Include counts: Provide real numbers for scale section
- Add line references: For business rules, include
file.ts:line - Update timestamp: Always update the "Last updated" date
- Preserve structure: Keep the same section headings for consistency