engineering-knowledge

Engineering Knowledge

This skill governs the engineering knowledge modules of the Personal Brain OS. It covers architecture decisions, debugging logs, tech debt tracking, engineering patterns, and project tracking. These files capture the accumulated engineering judgment that compounds over time — past decisions, hard-won debugging insights, and evolving code conventions.

The engineering knowledge module manages both entity directories (decisions, debugging, tech-debt) that require glob + frontmatter scanning and static narrative files (patterns, projects) that are loaded in full. Observation masking is critical for entity directories to avoid context bloat.

---

When to Use This Skill

Load this skill for any of the following:

• Architecture decisions — logging, searching, or referencing past ADRs
• Debugging sessions — recording a debugging session, searching past sessions for similar symptoms, or reviewing investigation patterns
• Tech debt tracking — logging new tech debt, prioritizing existing items, or reviewing debt status
• Engineering patterns — checking personal coding conventions, architecture preferences, or testing philosophy
• Project tracking — checking project status, cross-referencing ADRs or debugging entries with a project, or updating the project registry
• Code review notes — capturing patterns or decisions that emerged during code review

Do NOT load this skill for personal identity, content creation, contact lookups, goal tracking, or journaling — those belong to other modules.

---

Files in This Module

All paths relative to ~/brain/:

File	Purpose	When to Load
code/decisions/	Directory of ADR .md files	When logging or searching architecture decisions
code/debugging/	Directory of debugging entry .md files	When logging or searching past debugging sessions
code/tech-debt/	Directory of tech debt item .md files	When tracking or prioritizing tech debt
code/patterns.md	Narrative engineering patterns reference	When user asks about coding patterns or conventions
code/projects.yaml	Project registry with status	When checking project status or cross-referencing

Setup check: If any of these files or directories is missing, inform the user and suggest using the /bootstrap command to create them from the reference templates in skills/engineering-knowledge/references/.

---

Behavioral Rules

These rules operationalize observation masking and efficient file access for the engineering knowledge module. They are non-negotiable for all engineering queries.

Rule EK-1 — ADR Search

When searching architecture decisions:

1. Glob code/decisions/*.md
2. Load frontmatter only: id, date, status, tags, project
3. Filter by user query (tags, project, date range, status)
4. Present matching ADR summaries from frontmatter
5. Load body of a specific ADR only when the user requests full context or when you need the detail to answer the question

Never load all ADR bodies at once. Frontmatter-first scanning prevents context bloat.

Rule EK-2 — Debugging Triage

When searching past debugging sessions:

1. Glob code/debugging/*.md
2. Load frontmatter only for initial scan: id, date, project, difficulty, tags, status
3. Filter by tags matching the current symptom or error
4. Present matching entry summaries from frontmatter
5. Load body of top 2–3 matches for detailed investigation steps and root cause

If the user is logging a new debugging session (not searching), skip the scan and create a new entry from the template.

Rule EK-3 — Tech Debt Prioritization

When tracking or reviewing tech debt:

1. Glob code/tech-debt/*.md
2. Load frontmatter only: id, project, severity, effort, impact, status
3. Filter status: open by default (unless the user asks for all statuses)
4. Sort by severity (critical > high > medium > low)
5. Present prioritized list from frontmatter

Load body of a specific tech debt item only when the user needs the full description or proposed fix.

Rule EK-4 — Pattern Reference

When the user asks about coding patterns, conventions, or engineering preferences:

1. Load ~/brain/code/patterns.md in full — it is a narrative file, not an entity directory
2. Reference the relevant section to answer the question
3. If patterns.md is absent: inform the user and suggest bootstrapping from the template

Do not glob or scan patterns.md — always load it completely.

Rule EK-5 — Project Cross-Reference

When ADRs, debugging entries, or tech debt items reference a project:

1. Load ~/brain/code/projects.yaml for project context
2. Use the project registry to provide status, stack, and repo information alongside the engineering artifact
3. If a user asks about project status directly, load projects.yaml and present the relevant entry

---

Observation Masking

When searching engineering decisions: glob code/decisions/*.md, load frontmatter only (id, date, status, tags, project). Load body of specific ADR files only when full context is needed. When searching debugging entries: glob code/debugging/*.md, filter by tags matching current symptom, load frontmatter only for initial triage, then load body of top 2–3 matches. Tech debt: glob code/tech-debt/*.md, filter status: open, sort by severity.

---

Reference Templates

These files live in skills/engineering-knowledge/references/ and serve as the starting templates for bootstrapping the user's ~/brain/code/ directories. Use /bootstrap to copy them into the vault.

Template	Copies To	Purpose
adr-template.md	~/brain/code/decisions/	Architecture Decision Record template
debugging-template.md	~/brain/code/debugging/	Debugging session log template
tech-debt-template.md	~/brain/code/tech-debt/	Tech debt item template
patterns-template.md	~/brain/code/patterns.md	Engineering patterns narrative reference
projects-template.yaml	~/brain/code/projects.yaml	Project registry with status tracking

---

Version Notes

• v1.0.0 — Phase 2A: initial engineering-knowledge sub-skill. Covers code decisions, debugging, tech debt, patterns, and project tracking. Entity directories use frontmatter-only scanning with observation masking. Behavioral rules EK-1 through EK-5 implement efficient context loading.