synaptiai/agent-capability-standard/explain

explanation: string  # Full explanation at appropriate depth
summary: string  # 1-2 sentence overview
level: beginner | intermediate | expert
analogies: array[string]  # Helpful comparisons
key_concepts:
  - term: string  # Concept or term
    definition: string  # Clear definition
    relevance: string  # Why it matters here
premises:  # Supporting premises the reasoning starts from
  - premise: string
    evidence: string | null
chain:  # Reasoning chain
  - step: integer
    claim: string  # What is being claimed
    reasoning: string  # Why this follows
    evidence: string | null  # Supporting evidence
assumptions:
  - assumption: string  # What is assumed
    impact: string  # What happens if false
    testable: boolean  # Can this be verified
caveats:
  - caveat: string  # Limitation or exception
    severity: minor | moderate | significant
confidence: 0..1
evidence_anchors: ["file:line", "url", "doc:section"]

conclusion: "Why we chose PostgreSQL over MongoDB for the user service"
audience: intermediate
constraints:
  format: structured

explanation: |
  The user service manages core user data including profiles, authentication,
  and relationships between users. After evaluating PostgreSQL and MongoDB,
  we chose PostgreSQL for three primary reasons:
 
  1. **ACID Compliance**: User data requires strong consistency. When a user
     updates their email, all subsequent reads must see the new value. PostgreSQL's
     ACID transactions guarantee this; MongoDB's eventual consistency model would
     require additional application logic.
 
  2. **Relational Data Model**: User data is inherently relational - users have
     roles, roles have permissions, users have relationships with other users.
     PostgreSQL's foreign keys and JOINs model this naturally. MongoDB would
     require denormalization or multiple queries.
 
  3. **Team Expertise**: Our team has 5+ years of PostgreSQL experience.
     Estimated ramp-up time for MongoDB was 3 months, adding risk to the timeline.
summary: "PostgreSQL was selected for the user service due to strong ACID compliance, relational data patterns, and team expertise."
level: intermediate
analogies:
  - "ACID transactions are like bank transfers - the money leaves one account and arrives in another atomically, never losing money in transit"
  - "Relational data is like a spreadsheet with linked tabs - change a value in one tab and lookups from other tabs reflect it automatically"
key_concepts:
  - term: "ACID"
    definition: "Atomicity, Consistency, Isolation, Durability - properties ensuring reliable database transactions"
    relevance: "Critical for user data where partial updates could corrupt state"
  - term: "Eventual Consistency"
    definition: "Data will become consistent across replicas eventually, but reads may see stale data temporarily"
    relevance: "Acceptable for analytics, problematic for auth data"
  - term: "Denormalization"
    definition: "Duplicating data across documents to avoid JOINs"
    relevance: "MongoDB pattern that increases storage and update complexity"
premises:
  - premise: "Authentication and authorization decisions cannot tolerate stale data"
    evidence: "Security requirements doc section 2.3"
  - premise: "The user data model has 12 foreign key relationships"
    evidence: "Data model diagram"
  - premise: "5 of 7 developers are proficient in PostgreSQL"
    evidence: "Team skills inventory"
chain:
  - step: 1
    claim: "User data requires strong consistency"
    reasoning: "Authentication and authorization decisions cannot tolerate stale data"
    evidence: "Security requirements doc section 2.3"
  - step: 2
    claim: "PostgreSQL provides stronger consistency than MongoDB"
    reasoning: "ACID transactions vs eventual consistency model"
    evidence: "PostgreSQL docs: transaction isolation; MongoDB docs: read concern"
  - step: 3
    claim: "User data is relational in nature"
    reasoning: "Users have roles, roles have permissions, users have social connections"
    evidence: "Data model diagram shows 12 foreign key relationships"
  - step: 4
    claim: "Team can deliver faster with PostgreSQL"
    reasoning: "Existing expertise reduces development and debugging time"
    evidence: "Team skills inventory shows 5/7 developers proficient in PostgreSQL"
  - step: 5
    claim: "PostgreSQL is the better choice for this use case"
    reasoning: "Meets consistency requirements, fits data model, leverages team skills"
    evidence: null
assumptions:
  - assumption: "User data consistency requirements will not relax"
    impact: "If relaxed, MongoDB's flexibility might become more attractive"
    testable: true
  - assumption: "Team composition remains stable"
    impact: "New hires might have MongoDB expertise, changing the calculus"
    testable: true
caveats:
  - caveat: "MongoDB would be better for highly variable schema data"
    severity: minor
  - caveat: "At massive scale, PostgreSQL horizontal scaling is harder than MongoDB"
    severity: moderate
confidence: 0.9
evidence_anchors:
  - "doc:security-requirements:section-2.3"
  - "doc:data-model-diagram"
  - "doc:team-skills-inventory"

conclusion: "What is a database index and why does it matter?"
audience: beginner
constraints:
  format: structured

explanation: |
  Imagine you have a phonebook with millions of entries. To find "John Smith", you
  could start at page 1 and read every entry until you find him. That would take
  forever! Instead, you use the alphabetical ordering - jump to "S", then find
  "Smith", then find "John Smith". Much faster!
 
  A database index works the same way. Without an index, the database reads every
  row to find what you want (called a "table scan"). With an index on the right
  column, it can jump directly to matching rows.
 
  **When to use indexes:**
  - Columns you search frequently (WHERE clauses)
  - Columns you sort by (ORDER BY)
  - Columns used to join tables
 
  **The trade-off:**
  Indexes speed up reading but slow down writing. Each time you add or update data,
  all relevant indexes must also be updated. Like maintaining multiple indexes for
  a book - more work for the author, but readers find things faster.
summary: "A database index is like a book's index - it helps find data quickly without reading everything."
level: beginner
analogies:
  - "A database index is like a book's index - it tells you exactly which page to turn to"
  - "Without an index, searching is like reading every page of a book to find one word"
  - "Creating too many indexes is like having a 100-page index for a 50-page book - the overhead outweighs the benefit"
key_concepts:
  - term: "Table Scan"
    definition: "Reading every row in a table to find matching data"
    relevance: "What happens without an index - slow for large tables"
  - term: "Index"
    definition: "A data structure that maps column values to row locations"
    relevance: "Enables fast lookups without reading all data"
  - term: "Trade-off"
    definition: "Gaining one thing by giving up another"
    relevance: "Faster reads but slower writes"
premises:
  - premise: "Real tables can hold millions of rows"
    evidence: null
  - premise: "Without an index the database must check each row"
    evidence: null
chain:
  - step: 1
    claim: "Tables can have millions of rows"
    reasoning: "Real applications accumulate data over time"
    evidence: null
  - step: 2
    claim: "Finding specific rows requires checking each row without an index"
    reasoning: "Database has no other way to know which rows match"
    evidence: null
  - step: 3
    claim: "Indexes provide a shortcut to relevant rows"
    reasoning: "Like alphabetical ordering in a phonebook"
    evidence: null
  - step: 4
    claim: "Queries using indexed columns are much faster"
    reasoning: "Jump directly to matching rows instead of scanning all"
    evidence: "Query on indexed column: 5ms vs non-indexed: 2000ms"
assumptions:
  - assumption: "Reader understands what a database is"
    impact: "May need to explain databases first"
    testable: true
  - assumption: "Book/phonebook analogy is familiar"
    impact: "Digital natives may not relate to phonebooks"
    testable: true
caveats:
  - caveat: "Indexes are not always the answer - small tables may not benefit"
    severity: minor
  - caveat: "Choosing wrong columns to index wastes resources"
    severity: moderate
confidence: 0.95
evidence_anchors:
  - "example:query-timing-comparison"