ccpe-system/model-cards

Model Cards

1. Purpose

This directory stores canonical and draft Model Cards.

A Model Card is the structured record of a single cognitive model.

Model Cards preserve the user's reusable intellectual assets independently of any one Agent, Skill, or Runtime.

2. Directory Structure

Recommended subdirectories:

model-cards/
├── foundational/
├── intermediate/
├── applied/
├── workflow-models/
└── implicit-extracted/

3. Subdirectory Usage

3.1 foundational/

Use for deep models that support many others.

Examples:

prediction-error-model.md
algorithmic-compression-model.md
causal-intervention-model.md

3.2 intermediate/

Use for mid-level models that structure a domain or reasoning pattern.

Examples:

cognitive-imaging-model.md
giant-cognition-model.md
cognitive-prism-model.md

3.3 applied/

Use for models designed for specific tasks.

Examples:

argument-repair-model.md
strategic-risk-review-model.md
concept-boundary-inspection-model.md

3.4 workflow-models/

Use for models that naturally become repeatable procedures.

Examples:

article-to-model-extraction-model.md
review-committee-workflow-model.md

3.5 implicit-extracted/

Use for models inferred from writing rather than explicitly named by the user.

These should usually start with status:

candidate

4. Model Card Requirements

Each Model Card should include:

Model Name
Model ID
Aliases
Source Material
Model Type
Layer
Status
Core Problem
Scope
Non-Scope
Core Assumptions
Core Mechanism
Procedure / Operating Logic
Inputs
Outputs
Failure Modes
Falsification Boundary
Related Models
Related Agents
Related Skills
Runtime Usage
Evaluation Criteria
Version Notes
Open Questions

5. Status Values

Use:

candidate
draft
active
rejected
merged
deprecated
archived

Only mark a Model Card as active after user confirmation.

6. Naming Convention

Use lowercase kebab-case.

Recommended pattern:

{model-id}-model.md

Examples:

cognitive-imaging-model.md
giant-cognition-model.md
cognitive-prism-model.md

7. Relationship to Model Index

Every important Model Card should appear in:

model-index/model-index.md

If a Model Card is used by Agents or Skills, update:

model-index/model-usage-map.md

If a Model Card depends on or overlaps with other models, update:

model-index/model-dependency-map.md

8. Candidate Models

Candidate models may be incomplete.

They should clearly mark:

confidence
review_status
open_questions

Do not build major canonical Agents or Skills on weak candidate models without warning.

9. Model Card Promotion

Candidate → Draft when:

Model structure is clear.
Source is identified.
Scope and mechanism are present.

Draft → Active when:

User confirms the model.
Model has falsification boundary.
Model Index is updated.
Usage map is updated if relevant.

10. Final Rule

A Model Card should make a model easier to use without making it shallower.

It should preserve generative structure, not merely summarize prose.