gabrielmoreira Architecture Refinement Skill
Meta-skill for maintaining and evolving the AI assistant's cognitive architecture through deliberate documentation and pattern extraction.
Purpose
This skill enables the AI assistant to:
- Recognize when a learning session produces architecture-worthy insights
- Document patterns in the appropriate .github/ location (skills, instructions, prompts)
- Update migration trackers and status tables
- Consolidate knowledge files following KISS/DRY principles
When to Apply
Trigger this skill when:
- A session resolves a recurring problem (document the pattern)
- A skill file is migrated or consolidated (update trackers)
- A new workflow emerges (capture in appropriate .instructions.md)
- User feedback reveals a principle ("don't over-simplify")
Core Patterns
Pattern Recognition Checklist
Before session ends, ask:
| Question | If Yes → Action |
|---|---|
| Did we solve a problem that could recur? | Document in relevant skill file |
| Did we learn something about the AI assistant's architecture? | Update relevant .github/ documentation |
| Did a file get created/deleted/consolidated? | Update migration trackers |
| Did user correct AI behavior? | Add to skill's Anti-Patterns + document principle |
| Did the skill itself get improved during use? | Commit the refinement immediately |
Documentation Location Guide
| What You Learned | Where to Document | Audience |
|---|---|---|
| Technical skill pattern | .github/skills/{name}/SKILL.md |
the AI assistant (AI) |
| Important concepts for user | .github/skills/{name}/SKILL.md |
Human + AI |
| Process improvement | .github/instructions/*.instructions.md |
the AI assistant (AI) |
| Complex workflow | .github/prompts/*.prompt.md |
the AI assistant (AI) |
| Domain expertise | .github/skills/{name}/SKILL.md |
the AI assistant (AI) |
Key Distinction:
.github/skills/= Operational reference during work (the AI assistant + user)
Consolidation Decision Tree
- >50% overlap with existing skill → Consolidate INTO it, update tracker as "Consolidated"
- <50% overlap → Create new skill, add to tracker as "Migrated"
Pattern Extraction Template
When documenting a learned pattern:
### [Pattern Name]
**Pattern**: [One-sentence description of what to do]
**Example**: [Concrete instance from the session]
**Why**:
- [Reason 1]
- [Reason 2]
**Anti-pattern**: [What NOT to do, if applicable]
Quality Checks
Before committing documentation updates:
- Markdown lint-clean (blank lines around lists, proper headings)
- Tables have header separators
- No orphaned references to deleted files
- Migration trackers reflect current state
- Commit message follows conventional format
Anti-Patterns
| Don't | Do Instead |
|---|---|
| Document every minor fix | Only architecture-worthy insights |
| Create new file for each learning | Consolidate into existing structure |
| Wait until end of session | Document as patterns emerge |
| Over-document obvious things | Focus on non-obvious learnings |
| Skip human feedback | Capture corrective principles explicitly |
User Coaching Learning Loop
User corrections = high-value learning.
Protocol: Acknowledge → Fix → Extract principle → Document in skill → Commit
| AI Tendency | User Correction | Extracted Principle |
|---|---|---|
| Over-centralize | "Don't dump in one file" | Distribute to appropriate locations |
| Over-simplify | "You lost context" | Preserve nuance when consolidating |
| Skip validation | "Did you check it?" | Always verify (lint, count chars) |
| Assume completion | "What about X?" | Follow through on all aspects |
| Add diagrams to skills | "KISS them goodbye" | Skills are for AI, not visual learners |
Connection to Bootstrap Learning
Learn → Coach → Extract → Document → Consolidate