Construyendo un Segundo Cerebro para el Desarrollo de Software

// ❌ Over-structured capture that nobody maintains
interface OverEngineeredNote {
  id: string;
  title: string;
  category: string;
  subcategory: string;
  tags: string[];
  relatedTopics: string[];
  difficulty: "beginner" | "intermediate" | "advanced";
  lastReviewed: Date;
  reviewInterval: number;
  content: string;
  references: { url: string; title: string; accessDate: Date }[];
}
// Result: you capture nothing because the form takes 5 minutes

// ✅ Low-friction capture that actually gets used
interface QuickCapture {
  content: string;    // The actual knowledge
  context?: string;   // Where you learned it / why it matters
  tags?: string[];    // Optional, add later during review
  timestamp: Date;    // Automatic
}
 
function captureNote(content: string, context?: string): QuickCapture {
  return {
    content,
    context,
    timestamp: new Date(),
  };
}
 
// Examples of actual quick captures:
const realNotes: QuickCapture[] = [
  captureNote(
    "PostgreSQL EXPLAIN ANALYZE shows actual vs estimated rows. " +
    "When ratio > 10x, stats are stale — run ANALYZE on the table.",
    "Found while debugging slow query on orders table"
  ),
  captureNote(
    "Node.js streams: pipe() auto-handles backpressure. " +
    "Manual event listening with on('data') does NOT.",
    "Production memory spike caused by fast producer, slow consumer"
  ),
  captureNote(
    "CSS :has() selector lets parent style based on children. " +
    "form:has(:invalid) { border-color: red; }",
    "Replaced 20 lines of JS form validation styling"
  ),
];

interface KnowledgeBase {
  areas: KnowledgeArea[];
}
 
interface KnowledgeArea {
  name: string;
  description: string;
  examples: string[];
}
 
const developerKB: KnowledgeBase = {
  areas: [
    {
      name: "Debugging Playbooks",
      description: "Step-by-step procedures for diagnosing specific issues",
      examples: [
        "Memory leak investigation checklist",
        "Database slow query diagnosis steps",
        "Container OOMKilled debugging flow",
        "Network timeout investigation procedure",
      ],
    },
    {
      name: "Decision Records",
      description: "Why we chose X over Y, with context",
      examples: [
        "Why we picked Redis over Memcached for sessions",
        "Trade-offs: monorepo vs polyrepo (our context)",
        "Why we chose GraphQL for the mobile API",
      ],
    },
    {
      name: "Code Patterns",
      description: "Reusable solutions to recurring problems",
      examples: [
        "TypeScript discriminated union error handling",
        "React: data fetching with abort controller",
        "PostgreSQL: recursive CTE for tree structures",
      ],
    },
    {
      name: "Incident Learnings",
      description: "What broke, why, and how to prevent it",
      examples: [
        "2023-03 outage: connection pool exhaustion",
        "Deploy rollback: migration incompatibility",
        "Cache stampede during cold start",
      ],
    },
  ],
};

interface SearchableNote {
  id: string;
  content: string;
  context: string;
  tags: string[];
  created: Date;
  lastAccessed: Date;
  accessCount: number;
}
 
interface SearchResult {
  note: SearchableNote;
  relevanceScore: number;
  matchedOn: ("content" | "context" | "tags")[];
}
 
function searchNotes(
  notes: SearchableNote[],
  query: string
): SearchResult[] {
  const queryTerms = query.toLowerCase().split(/\s+/);
  const results: SearchResult[] = [];
 
  for (const note of notes) {
    let score = 0;
    const matchedOn: ("content" | "context" | "tags")[] = [];
 
    const contentLower = note.content.toLowerCase();
    const contextLower = note.context.toLowerCase();
    const tagsLower = note.tags.map(t => t.toLowerCase());
 
    for (const term of queryTerms) {
      if (contentLower.includes(term)) {
        score += 3;
        if (!matchedOn.includes("content")) matchedOn.push("content");
      }
      if (contextLower.includes(term)) {
        score += 2;
        if (!matchedOn.includes("context")) matchedOn.push("context");
      }
      if (tagsLower.some(t => t.includes(term))) {
        score += 1;
        if (!matchedOn.includes("tags")) matchedOn.push("tags");
      }
    }
 
    // Boost frequently accessed notes
    score += Math.log2(note.accessCount + 1) * 0.5;
 
    // Boost recently accessed notes
    const daysSinceAccess =
      (Date.now() - note.lastAccessed.getTime()) / (1000 * 60 * 60 * 24);
    if (daysSinceAccess < 30) {
      score += 1;
    }
 
    if (score > 0) {
      results.push({ note, relevanceScore: score, matchedOn });
    }
  }
 
  return results.sort((a, b) => b.relevanceScore - a.relevanceScore);
}

interface WeeklyReviewChecklist {
  phase: string;
  duration: string;
  steps: string[];
}
 
const weeklyReview: WeeklyReviewChecklist[] = [
  {
    phase: "Process Inbox",
    duration: "10 minutes",
    steps: [
      "Review all quick captures from the week",
      "Add tags to untagged notes",
      "Link related notes together",
      "Discard notes that no longer seem valuable",
    ],
  },
  {
    phase: "Refine Patterns",
    duration: "10 minutes",
    steps: [
      "Look for repeated themes across new notes",
      "Merge similar notes into consolidated entries",
      "Upgrade debugging solutions into playbooks",
      "Turn one-off code snippets into reusable patterns",
    ],
  },
  {
    phase: "Connect and Reflect",
    duration: "10 minutes",
    steps: [
      "Ask: What did I learn this week that surprised me?",
      "Ask: What problem took longest? Could better notes have helped?",
      "Link new learnings to existing decision records",
      "Identify knowledge gaps worth investigating next week",
    ],
  },
];

// Tracking knowledge system health
interface KBHealthMetrics {
  totalNotes: number;
  notesThisWeek: number;
  searchesThisWeek: number;
  searchHitRate: number;       // searches that found useful results
  avgNoteAge: number;          // days
  orphanedNotes: number;       // no tags, no links
  staleNotes: number;          // not accessed in 6+ months
}
 
function assessKBHealth(metrics: KBHealthMetrics): string[] {
  const suggestions: string[] = [];
 
  if (metrics.notesThisWeek < 3) {
    suggestions.push(
      "Low capture rate. Are you solving problems without recording solutions?"
    );
  }
 
  if (metrics.searchHitRate < 0.5) {
    suggestions.push(
      "Search hit rate below 50%. Notes might need better tagging or " +
      "the search terms don't match your capture vocabulary."
    );
  }
 
  if (metrics.orphanedNotes > metrics.totalNotes * 0.3) {
    suggestions.push(
      `${metrics.orphanedNotes} orphaned notes (${
        ((metrics.orphanedNotes / metrics.totalNotes) * 100).toFixed(0)
      }%). Spend review time adding tags and links.`
    );
  }
 
  if (metrics.staleNotes > metrics.totalNotes * 0.5) {
    suggestions.push(
      "Over half your notes haven't been accessed in 6 months. " +
      "Archive or prune during next review."
    );
  }
 
  return suggestions;
}

const templates = {
  debuggingSolution: (problem: string, solution: string, rootCause: string) => `
## ${problem}
 
**Root Cause:** ${rootCause}
 
**Solution:**
${solution}
 
**How to detect earlier:** [fill in during review]
`,
 
  decisionRecord: (decision: string, options: string[], rationale: string) => `
## Decision: ${decision}
 
**Options Considered:**
${options.map((o, i) => `${i + 1}. ${o}`).join("\n")}
 
**Choice:** Option [X]
 
**Rationale:** ${rationale}
 
**Revisit if:** [conditions that would change this decision]
`,
 
  codePattern: (name: string, problem: string, code: string) => `
## ${name}
 
**Problem:** ${problem}
 
\`\`\`typescript
${code}
\`\`\`
 
**When to use:** [fill in]
**Watch out for:** [fill in]
`,
};