cognitive-artifacts

name

cognitive-artifacts

description

Build CADSL-based cognitive artifacts for sea-domain-forge including checklists, planners, decision trees, kanban boards, mind maps, and timelines. Use for generating interactive, semantically-anchored artifacts that support knowledge work and collaborative decision-making. Aligns with Cognitive Architecture patterns and Knowledge Graph integration. Invoked by conversation-to-spec, domain-expert-guide, case-management, and doc-coauthoring skills.

Cognitive Artifacts Builder

Generate CADSL (Cognitive Artifact DSL) artifacts for SEA-Forge™ to support knowledge work. CADSL artifacts are declarative, semantically-rich, platform-agnostic definitions that render across web, mobile, and voice interfaces.

No-Technical-Debt Rule

This skill forbids placeholders of any kind:

• No TODO/FIXME/XXX/HACK/STUB markers
• No stubs, mocks-as-implementations, or empty handlers
• No raise NotImplementedError / throw new Error("not implemented")
• No pass or placeholder logic

When to Use This Skill

1. Organizing Knowledge: User needs structured representation of complex information
2. Supporting Decisions: User is evaluating options or making strategic choices
3. Tracking Work: User needs to manage tasks, projects, or workflows
4. Facilitating Collaboration: Team needs a shared artifact for alignment
5. Visualizing Relationships: User wants to see connections between concepts

Artifact Type Selection

User Need	Artifact
Track completion of tasks	Checklist
Choose between options	Decision Tree / Planner
Manage workflow stages	Kanban Board
Explore concept relationships	Mind Map
Plan over time	Timeline / Roadmap

Artifact Type Catalog

1. Checklist

Purpose: Track completion of sequential or independent tasks

Elements: Heading, Checkbox, Label, ProgressBar

CADSL Example:

artifactType: Checklist
metadata:
  title: "Production Deployment Checklist"
  semanticRefs:
    - conceptId: "sea:Deployment"
    - conceptId: "sea:QualityGate"
  provenance:
    generatedBy: "cognitive-artifacts"
    timestamp: "<ISO 8601>"

sections:
  - id: "pre-deploy"
    heading: "Pre-Deployment Quality Gates"
    semanticRefs:
      - conceptId: "sea:QualityGate"
    items:
      - id: "test-pass"
        checkbox: true
        completed: false
        label: "All tests passing (CI/CD)"
        semanticRefs:
          - conceptId: "sea:ContinuousIntegration"
      - id: "review-complete"
        checkbox: true
        completed: false
        label: "Code review approved"

---

2. Decision Tree / Planner

Purpose: Guide users through conditional decision-making paths

Elements: Heading, Section, RadioButton, Button, Arrow, Conditional

Use Cases:

• Architecture decision records (ADR)
• Troubleshooting guides
• Policy routing
• Feature selection wizards

---

3. Kanban Board

Purpose: Visualize workflow states and move items through stages

Elements: Panel, Section, DragAndDropArea, Card, Badge, ProgressIndicator

Default Columns: Backlog | In Progress | Review | Done

CMMN Integration: Columns map to CMMN stages. Cards map to case tasks.

---

4. Mind Map / Concept Map

Purpose: Visualize hierarchical or networked relationships between concepts

Elements: Canvas, Node (circle/box), Line, Arrow, Label, Grouping

Use Cases: Brainstorming, system architecture overview, dependency mapping

---

5. Timeline / Roadmap

Purpose: Chronological representation of events, milestones, or plans

Elements: Timeline, Calendar, Schedule, ProgressBar, Badge

CADSL Example:

artifactType: Timeline
metadata:
  title: "Q1 Product Launch Roadmap"
  semanticRefs:
    - conceptId: "sea:Milestone"
  provenance:
    generatedBy: "cognitive-artifacts"
    timestamp: "<ISO 8601>"

milestones:
  - date: "<ISO 8601 date>"
    label: "PRD Complete"
    semanticRef: "sea:Specification"
  - date: "<ISO 8601 date>"
    label: "Design Complete"
  - date: "<ISO 8601 date>"
    label: "Development Complete"
  - date: "<ISO 8601 date>"
    label: "Launch"
    semanticRef: "sea:Release"

---

Generation Workflow

Step 1: Analyze Context

Extract from conversation:

• Task/Goal: What is the user trying to accomplish?
• Information Structure: Linear? Hierarchical? Networked? Temporal?
• Interaction Needs: View-only? Editable? Collaborative?
• Semantic Context: Related concepts from Knowledge Graph

Step 2: Recommend Artifact Type

Based on analysis, suggest the most appropriate artifact:

"Would a Checklist help track these requirements? Here's what it would include."

Always present a brief preview before generating the full artifact.

Step 3: Generate CADSL Definition

Required metadata on every artifact:

metadata:
  title: "<descriptive title>"
  semanticRefs:
    - conceptId: "<sea:Concept>"
  provenance:
    generatedBy: "cognitive-artifacts"
    timestamp: "<ISO 8601>"

Semantic Anchoring (mandatory):

• Every artifact MUST include semanticRefs linking to Knowledge Graph concepts
• Use conceptId format: sea:Order or order-fulfillment:Shipment

Step 4: Present Artifact

1. Show CADSL definition in a code block
2. Walk through sections and key elements
3. Point out Knowledge Graph connections
4. Suggest interactions: "You can edit this now", "I can update it on request"

Step 5: Iterate

Support refinement with precise updates:

• "Add a new column to the kanban board"
• "Change this checklist item priority to critical"
• "Link this decision tree node to ADR-034"

Modify specific sections of YAML rather than regenerating the entire artifact.

Epistemic Status of Artifacts

• Artifacts generated during discovery (Phases 1–2 of conversation-to-spec) are observed
• Artifacts become confirmed only after the user explicitly validates them
• Never present an artifact as authoritative before the user has reviewed it

Quality Guidelines

Semantic Richness (required):

# ❌ Bad: Generic labels
heading: "Items"
items:
  - label: "Task 1"

# ✅ Good: Descriptive, semantically linked
heading: "Pre-Deployment Quality Gates"
semanticRefs:
  - conceptId: "sea:QualityGate"
items:
  - label: "All tests passing (CI/CD)"
    semanticRefs:
      - conceptId: "sea:ContinuousIntegration"

Provenance Tracking (required): Always include:

• generatedBy: The skill that created the artifact
• timestamp: When the artifact was created
• sourceDoc: Optional reference to originating specification

Actionability: Artifacts enable action, not just display.

• Buttons with command or link properties
• Interactive elements (checkboxes, drag-and-drop)
• Clear next steps visible in the artifact itself

Integration Points

Skill	How
conversation-to-spec	Generates discovery artifacts (checklists, decision trees) during Phases 1–2
case-management	Kanban boards map to CMMN stages; artifacts move through pipeline
doc-coauthoring	Checklists validate doc completeness during Stage 3 reader testing
pm-orchestration	PM-Agent can trigger artifact generation when sentries fire