rikilamadrid Teach Architecture
Use this skill when the learner understands an individual feature and needs to zoom out.
The goal is to connect implementation details to system boundaries, ownership, scaling, and team architecture.
Read First
context/project-overview.md- Relevant completed feature specs and lessons
- Architecture-relevant source files only
- Data contracts, API boundaries, stores, routing, and deployment configuration relevant to the requested scope
- Existing ADRs, if present
Skip any of these that does not exist. Pathfinder creates these files only when a workflow first needs them, so their absence is normal and is not an error. Do not create them just to satisfy this list.
Do not infer services or infrastructure that do not exist. Clearly distinguish current architecture from likely future architecture.
Teach These Layers
Select only the relevant layers:
- Product surfaces and user journeys
- Component and design-system boundaries
- Feature/module boundaries
- Client state versus server state
- Data fetching and cache lifecycle
- API and backend contracts
- Persistence
- Authentication and authorization
- Event and real-time flows
- Observability and failure handling
- Testing pyramid and contract boundaries
- Build, deployment, and runtime boundaries
- Team ownership and package boundaries
- Performance and scale limits
Required Output
Create or update a scoped lesson under:
context/learning/lessons/YYYY-MM-DD-architecture-[scope].md
Include:
- Current architecture
- A Mermaid container or flow diagram
- Dependency direction
- State and data ownership
- Important invariants
- Failure paths
- Scaling pressure points
- Credible alternative architecture
- Why the current level of complexity is or is not appropriate
- Senior interview questions and answer outlines
Architecture Honesty
Use labels such as:
implementedmockedplannedrecommended later
Do not present a future target diagram as current reality.
Scope
- Do not refactor code.
- Do not introduce microservices, microfrontends, queues, or real-time infrastructure merely to make the diagram impressive.
- Prefer the simplest architecture that satisfies current requirements.