Systematic approach to understanding a new project repository — especially those governed by Kairos with Hindsight memory banks. Use this skill whenever a user says "familiarízate con el repo", "examina este proyecto", "entiende la infraestructura", or you need to orient before making changes.
Execute these steps in order. Each builds on the previous one.
-
Identify the active banks. Two banks are always needed:
- Project bank — matches the project directory/repo name (e.g.,
toolset → bank toolset).
- User profile bank — always bank
hermes (user preferences, conventions, meta-rules).
-
Run recall on both banks with broad, high-budget queries, in parallel:
mcp_hindsight_selfhosted_recall(
query="contexto completo del proyecto infraestructura arquitectura",
bank_id="<project-name>",
budget="high"
)
mcp_hindsight_selfhosted_recall(
query="perfil del usuario preferencias contexto del entorno",
bank_id="hermes",
budget="high"
)
-
Store the full outputs. Results are typically large (100+ KB with 50+ memories each). Save to temp files for later scanning (/tmp/hermes-results/*.txt).
-
Scan for key memory categories in each bank's results:
Project bank — look for:
- Infrastructure facts (
fact_type: world/observation about OCI, services, networking)
- Project progress (
fact_type: experience with context project_progress)
- Governance rules (
fact_type: observation tagged governance, lesson-learned)
- Document references (tags like
toolset_document, repomap)
- Architectural decisions (
tags: technical_decisions)
User profile bank (hermes) — look for:
- User preferences (tone, style, format, verbosity)
- Environment conventions (tool choices, workflows, project structure)
- Corrections and lessons learned (tagged
lesson-learned)
- Active directives or standing instructions
-
If the bank doesn't exist or is empty, note it and proceed — the repo's physical docs become your primary source.
-
Skipping the user profile bank (hermes) — recalling only the project bank means you miss user-level context: preferences, corrections, meta-rules that apply across all projects. Always recall BOTH banks.
-
Skipping Hindsight recall — per Kairos MEM-01, Hindsight MUST be the first step. Reading files first and then recalling duplicates effort and wastes context window.
-
Reading files out of order — REPOMAP defines the reading order. Always start with REPOMAP, then MASTER-SPEC, then RULES.
-
Treating all docs as equal — MASTER-SPEC.md is a Domain Axiom (architectural authority), TODO.md is documentation (task tracking). They have different authority levels. REPOMAP clarifies this.
-
Over-relying on git log — commit messages only show what changed, not why or how the system works. The documentary axis (docs/) and memory (Hindsight) provide the "why".
-
Ignoring .agents/ — the .agents/ directory is the active governance layer with roles, skills, workflows, and templates that define how the agent should operate in this repo. Per Kairos, it's a MUST-READ.
-
Forgetting .agents/ on new projects — Para CADA proyecto nuevo, .agents/ debe clonarse desde kirlts/kairos. No crearlo manualmente ni copiar de otro repo. Esto asegura reglas, templates y workflows consistentes en todos los proyectos del toolset.
-
/document en el repo equivocado — El workflow /document debe ejecutarse SIEMPRE en el contexto del repo kirlts/toolset (repo de gobierno central), NO en el repo donde se trabajó. Toolset contiene la configuración global, skills, y documentación de infraestructura.
-
Bank naming — Los banks de Hindsight se nombran EXACTAMENTE como el repo al que refieren (bank_id="researchit", no "ResearchIt Engine"). El name (nombre amigable) también debe ser el nombre del repo.
-
Secrets no van en código — Todos los secrets (API keys, connection IDs) van en Infisical, respaldados por GitHub Secrets. No hardcodear en el código fuente. Ver kilo-code skill para el patrón de exportación (set -a && source .env).
