Cks Usage

Architecture Alignment

• Integrates with /cks (knowledge search), /search (unified search), /analyze (analysis)
• Links to /learn (session learning)
• Part of knowledge management ecosystem

Your Workflow

1. DETECT VIOLATIONS — Check for JSON writes to data/cks/, file I/O for knowledge, /learn invocation
2. STOP IMMEDIATELY — Halt any incorrect flat file creation
3. USE PROPER API — Invoke DirectCKSIngestion.ingest_knowledge()
4. VERIFY INGESTION — Confirm entry exists via search_knowledge()
5. SHOW STATISTICS — Display CKS statistics after ingestion
6. CLEANUP — Remove any incorrectly created flat files

Validation Rules

• Before knowledge storage: Must use DirectCKSIngestion, not file I/O
• After ingestion: Verify entry exists in database via search
• Before completing /learn: Show CKS statistics, confirm API usage
• Pattern detection: Catch JSON writes to data/cks/, flat file knowledge creation

Prohibited Actions

• Writing JSON files to data/cks/lessons/
• Creating knowledge as flat files
• Bypassing CKS ingestion API
• Using Path("data/cks/...").write_text() for knowledge

When This Skill Activates

When ANY of these patterns are detected:

• Writing .json files to data/cks/ directory
• Creating knowledge files outside CKS database
• Using file I/O for knowledge storage instead of CKS API
• /learn command invocation

What You MUST Do Instead

1. Use DirectCKSIngestion class from src.cks.integration.commands.direct_knowledge_ingestion

2. Proper ingestion pattern:

   from src.cks.integration.commands.direct_knowledge_ingestion import DirectCKSIngestion
   
   ingestion = DirectCKSIngestion()
   result = ingestion.ingest_knowledge(
       title="Lesson Title",
       content="Full lesson content...",
       category="technical_lessons",
       knowledge_type="lesson",
       tags=["tag1", "tag2"],
   )
   

3. For session learning (/learn):

   • Read any existing JSON files
   • Ingest into CKS using the API above
   • Optionally keep JSON as backup/reference but NOT primary storage

CKS Database Locations

Forbidden Patterns

❌ DO NOT:

• Write JSON files to data/cks/lessons/
• Create knowledge as flat files
• Bypass CKS ingestion API
• Use Path("data/cks/...").write_text() for knowledge

✅ DO:

• Use DirectCKSIngestion.ingest_knowledge()
• Verify ingestion with search_knowledge()
• Check statistics with get_statistics()
• Close connection when done

Validation

Before completing /learn or knowledge storage:

1. Confirm DirectCKSIngestion was used
2. Verify entry exists in database via search
3. Show CKS statistics after ingestion

Consequences

If you detect yourself taking the shortcut:

1. STOP immediately
2. Use proper CKS API
3. Remove any incorrectly created flat files
4. Ingest properly