758 lines
13 KiB
Markdown
758 lines
13 KiB
Markdown
# Model Card Rules
|
|
|
|
## 1. Purpose
|
|
|
|
This file defines how CCPE Forge should create, audit, and maintain Model Cards.
|
|
|
|
A Model Card is the canonical description of a single cognitive model.
|
|
|
|
It should preserve the model as an independent intellectual asset, separate from any one Agent, Skill, or Runtime.
|
|
|
|
## 2. What a Model Card Is
|
|
|
|
A Model Card describes a reusable cognitive structure.
|
|
|
|
It captures:
|
|
|
|
```text
|
|
What problem the model addresses
|
|
What assumptions it makes
|
|
What mechanism it proposes
|
|
Where it applies
|
|
Where it fails
|
|
How it can be used
|
|
How it can be tested
|
|
Which Agents, Skills, or Runtimes use it
|
|
```
|
|
|
|
A Model Card is not a persona.
|
|
|
|
A Model Card is not just a summary.
|
|
|
|
A Model Card is not merely a metaphor.
|
|
|
|
A Model Card is not automatically a Skill.
|
|
|
|
A Model Card is the model's source of truth.
|
|
|
|
## 3. When to Create a Model Card
|
|
|
|
Create or recommend a Model Card when an artifact contains a model that:
|
|
|
|
```text
|
|
Has independent explanatory or generative value
|
|
Can be reused across multiple agents or skills
|
|
Comes from long-form writing
|
|
Has identifiable assumptions
|
|
Has a mechanism
|
|
Has a scope
|
|
Has failure modes
|
|
Can define a falsification boundary
|
|
May become part of a model library
|
|
```
|
|
|
|
## 4. When Not to Create a Model Card
|
|
|
|
Do not create a Model Card for:
|
|
|
|
```text
|
|
A single claim
|
|
A slogan
|
|
A mood
|
|
A style preference
|
|
A loose metaphor without mechanism
|
|
A list of advice
|
|
A generic checklist
|
|
A temporary task procedure
|
|
An isolated example
|
|
A personal opinion without reusable structure
|
|
```
|
|
|
|
If uncertain, mark it as:
|
|
|
|
```text
|
|
Candidate Model
|
|
```
|
|
|
|
rather than promoting it to a canonical Model Card.
|
|
|
|
## 5. Model Card vs Other CCPE Artifacts
|
|
|
|
### 5.1 Model Card vs Agent
|
|
|
|
A Model Card defines the model.
|
|
|
|
An Agent uses the model.
|
|
|
|
Example:
|
|
|
|
```text
|
|
Cognitive Imaging Model Card:
|
|
Defines Capture, Darkroom, Enlarger, Exposure, Development as a model.
|
|
|
|
Cognitive Imaging Specialist Agent:
|
|
Uses the model in interaction with the user.
|
|
```
|
|
|
|
### 5.2 Model Card vs Skill
|
|
|
|
A Model Card explains the structure.
|
|
|
|
A Skill executes a procedure.
|
|
|
|
Example:
|
|
|
|
```text
|
|
Cognitive Imaging Model:
|
|
The theory and generative mechanism.
|
|
|
|
Cognitive Imaging Skill:
|
|
A callable procedure that applies the model to user input and produces a report.
|
|
```
|
|
|
|
### 5.3 Model Card vs Runtime
|
|
|
|
A Model Card defines a model.
|
|
|
|
A Runtime orchestrates work.
|
|
|
|
Example:
|
|
|
|
```text
|
|
Modeling Committee Runtime may orchestrate several agents and skills,
|
|
some of which use Cognitive Imaging, Giant Cognition, or Cognitive Prism models.
|
|
```
|
|
|
|
### 5.4 Model Card vs Model Index
|
|
|
|
A Model Card is one model.
|
|
|
|
A Model Index organizes many models.
|
|
|
|
The Model Card is the detailed record.
|
|
|
|
The Model Index is the map.
|
|
|
|
## 6. Canonical Model Card Structure
|
|
|
|
Use this structure for full Model Cards:
|
|
|
|
```md
|
|
---
|
|
artifact_type: model-card
|
|
model_name:
|
|
aliases:
|
|
author:
|
|
version:
|
|
created:
|
|
updated:
|
|
status: candidate
|
|
source_material:
|
|
model_type:
|
|
related_models:
|
|
related_agents:
|
|
related_skills:
|
|
related_runtimes:
|
|
---
|
|
|
|
# {Model Name}
|
|
|
|
## 1. Model Overview
|
|
|
|
## 2. Source Material
|
|
|
|
## 3. Core Problem
|
|
|
|
## 4. Scope
|
|
|
|
## 5. Non-Scope
|
|
|
|
## 6. Core Assumptions
|
|
|
|
## 7. Core Mechanism
|
|
|
|
## 8. Procedure / Operating Logic
|
|
|
|
## 9. Inputs
|
|
|
|
## 10. Outputs
|
|
|
|
## 11. Failure Modes
|
|
|
|
## 12. Falsification Boundary
|
|
|
|
## 13. Distinctions
|
|
|
|
## 14. Related Models
|
|
|
|
## 15. Related Agents
|
|
|
|
## 16. Related Skills
|
|
|
|
## 17. Runtime Usage
|
|
|
|
## 18. Examples
|
|
|
|
## 19. Evaluation Criteria
|
|
|
|
## 20. Version Notes
|
|
|
|
## 21. Open Questions
|
|
```
|
|
|
|
## 7. Required Fields
|
|
|
|
Every Model Card should include at minimum:
|
|
|
|
```text
|
|
Model Name
|
|
Source Material
|
|
Model Type
|
|
Core Problem
|
|
Scope
|
|
Core Assumptions
|
|
Core Mechanism
|
|
Failure Modes
|
|
Falsification Boundary
|
|
Status
|
|
```
|
|
|
|
A Model Card without mechanism is weak.
|
|
|
|
A Model Card without scope is dangerous.
|
|
|
|
A Model Card without failure mode tends to become ideology.
|
|
|
|
A Model Card without falsification boundary tends to become unfalsifiable explanatory fog.
|
|
|
|
## 8. Model Name
|
|
|
|
The model name should be stable, memorable, and specific.
|
|
|
|
If the user already has a name, preserve it unless there is a strong reason not to.
|
|
|
|
Use bilingual names when helpful:
|
|
|
|
```text
|
|
认知显影术 / Cognitive Imaging
|
|
巨人认知 / Giant Cognition
|
|
认知棱镜 / Cognitive Prism
|
|
```
|
|
|
|
For implicit extracted models, mark the name as provisional:
|
|
|
|
```text
|
|
Provisional Name:
|
|
```
|
|
|
|
## 9. Aliases
|
|
|
|
Aliases may include:
|
|
|
|
```text
|
|
Chinese name
|
|
English name
|
|
Short name
|
|
Former name
|
|
Working title
|
|
Related phrase used in source material
|
|
```
|
|
|
|
Aliases help link old articles, prompts, and discussions.
|
|
|
|
## 10. Source Material
|
|
|
|
Record the source of the model.
|
|
|
|
Possible sources:
|
|
|
|
```text
|
|
Article
|
|
Essay
|
|
Prompt appendix
|
|
Agent description
|
|
Conversation
|
|
Note
|
|
Lecture
|
|
Research draft
|
|
Knowledge base document
|
|
```
|
|
|
|
Include:
|
|
|
|
```text
|
|
Title
|
|
Path
|
|
Date
|
|
Author
|
|
Relevant sections
|
|
Extraction notes
|
|
```
|
|
|
|
If source is unknown, mark:
|
|
|
|
```text
|
|
source_material: unknown
|
|
```
|
|
|
|
Do not invent source metadata.
|
|
|
|
## 11. Model Type
|
|
|
|
Use one or more:
|
|
|
|
```text
|
|
foundational
|
|
intermediate
|
|
applied
|
|
workflow-model
|
|
implicit-extracted
|
|
candidate
|
|
deprecated
|
|
```
|
|
|
|
Definitions:
|
|
|
|
```text
|
|
foundational:
|
|
A deep model that supports many others.
|
|
|
|
intermediate:
|
|
A mid-level model that structures a domain or reasoning pattern.
|
|
|
|
applied:
|
|
A model designed for a specific practical use.
|
|
|
|
workflow-model:
|
|
A model that naturally becomes a repeatable process.
|
|
|
|
implicit-extracted:
|
|
A model inferred from writing rather than explicitly named.
|
|
|
|
candidate:
|
|
A possible model requiring review.
|
|
|
|
deprecated:
|
|
A model no longer recommended as canonical.
|
|
```
|
|
|
|
## 12. Status
|
|
|
|
Use:
|
|
|
|
```text
|
|
candidate
|
|
draft
|
|
active
|
|
rejected
|
|
merged
|
|
deprecated
|
|
archived
|
|
```
|
|
|
|
Default status for extracted models should be:
|
|
|
|
```text
|
|
candidate
|
|
```
|
|
|
|
or:
|
|
|
|
```text
|
|
draft
|
|
```
|
|
|
|
Only use `active` after user confirmation.
|
|
|
|
## 13. Core Problem
|
|
|
|
The Core Problem defines what the model is trying to solve.
|
|
|
|
Good Core Problem examples:
|
|
|
|
```text
|
|
How to identify generative structure inside complex adaptive systems.
|
|
How to distinguish real causal generators from surface correlations.
|
|
How to compress a long conceptual field into a usable explanatory algorithm.
|
|
```
|
|
|
|
Bad Core Problem examples:
|
|
|
|
```text
|
|
Think better.
|
|
Analyze things.
|
|
Understand cognition.
|
|
Improve writing.
|
|
```
|
|
|
|
The Core Problem should be specific enough to shape the model.
|
|
|
|
## 14. Scope
|
|
|
|
Scope defines where the model applies.
|
|
|
|
Include:
|
|
|
|
```text
|
|
Domain
|
|
Task type
|
|
Input type
|
|
Environmental assumptions
|
|
User goal
|
|
Level of uncertainty
|
|
```
|
|
|
|
Example:
|
|
|
|
```text
|
|
Applies to complex adaptive systems, unfamiliar domains, low-feedback environments,
|
|
and cases where linear intuition is likely to fail.
|
|
```
|
|
|
|
## 15. Non-Scope
|
|
|
|
Non-Scope defines where the model should not be used.
|
|
|
|
This prevents overgeneralization.
|
|
|
|
Example:
|
|
|
|
```text
|
|
Not intended for high-repetition, high-feedback expert tasks where trained intuition is more reliable,
|
|
such as routine surgical procedures or standard mechanical troubleshooting.
|
|
```
|
|
|
|
## 16. Core Assumptions
|
|
|
|
Core Assumptions define the model's foundation.
|
|
|
|
Good assumptions are:
|
|
|
|
```text
|
|
Explicit
|
|
Limited
|
|
Mechanism-related
|
|
Testable or at least challengeable
|
|
```
|
|
|
|
Avoid vague universal statements.
|
|
|
|
Example:
|
|
|
|
```text
|
|
Insight begins when prediction error is not immediately normalized by existing theory.
|
|
```
|
|
|
|
## 17. Core Mechanism
|
|
|
|
The Core Mechanism is the heart of the Model Card.
|
|
|
|
It should explain how the model generates insight or explanation.
|
|
|
|
Ask:
|
|
|
|
```text
|
|
What moves?
|
|
What transforms?
|
|
What causes what?
|
|
What filters what?
|
|
What compresses what?
|
|
What predicts what?
|
|
What breaks if the mechanism is wrong?
|
|
```
|
|
|
|
A model without mechanism is usually just a theme.
|
|
|
|
## 18. Procedure / Operating Logic
|
|
|
|
If the model has steps, define them.
|
|
|
|
Example:
|
|
|
|
```text
|
|
1. Capture prediction error.
|
|
2. Suspend premature interpretation.
|
|
3. Apply multiple disciplinary filters.
|
|
4. Test causal generators through intervention.
|
|
5. Compress the surviving structure into a falsifiable algorithm.
|
|
```
|
|
|
|
If the model has no fixed procedure, define operating logic instead.
|
|
|
|
## 19. Inputs
|
|
|
|
Define what the model can receive.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
Article
|
|
Argument
|
|
Phenomenon
|
|
Strategic situation
|
|
System behavior
|
|
Draft model
|
|
User question
|
|
Research notes
|
|
```
|
|
|
|
## 20. Outputs
|
|
|
|
Define what the model produces.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
Insight report
|
|
Core mechanism
|
|
Causal generator
|
|
Failure boundary
|
|
Question list
|
|
Model compression
|
|
Risk diagnosis
|
|
Reframed hypothesis
|
|
```
|
|
|
|
## 21. Failure Modes
|
|
|
|
Failure Modes define how the model goes wrong.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
Overgeneralization
|
|
Pseudo-profundity
|
|
Forced hard-science analogy
|
|
Mistaking correlation for causation
|
|
Turning every anomaly into meaningful signal
|
|
Ignoring domain-specific evidence
|
|
Unfalsifiable explanation
|
|
```
|
|
|
|
Failure Modes are essential for preserving model discipline.
|
|
|
|
## 22. Falsification Boundary
|
|
|
|
The Falsification Boundary defines what the model says should not happen, or what would weaken it.
|
|
|
|
Ask:
|
|
|
|
```text
|
|
What observation would challenge the model?
|
|
What input is outside scope?
|
|
What prediction would the model make?
|
|
What result would make the model less useful?
|
|
Where does the model become unfalsifiable?
|
|
What would turn it into a conspiracy-like explanation?
|
|
```
|
|
|
|
Good models have edges.
|
|
|
|
If the model explains everything, it explains nothing.
|
|
|
|
## 23. Distinctions
|
|
|
|
Use this section to distinguish the model from nearby concepts.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
Cognitive Imaging vs ordinary critique
|
|
Cognitive Imaging vs brainstorming
|
|
Cognitive Imaging vs confirmation bias hunting
|
|
Cognitive Imaging vs generic systems thinking
|
|
```
|
|
|
|
This helps prevent conceptual drift.
|
|
|
|
## 24. Related Models
|
|
|
|
List models that are:
|
|
|
|
```text
|
|
Parent models
|
|
Child models
|
|
Sibling models
|
|
Overlapping models
|
|
Conflicting models
|
|
Prerequisite models
|
|
Derived models
|
|
```
|
|
|
|
If unsure, mark:
|
|
|
|
```text
|
|
TBD
|
|
```
|
|
|
|
## 25. Related Agents
|
|
|
|
List agents that use or may use the model.
|
|
|
|
Example:
|
|
|
|
```text
|
|
Cognitive Imaging Specialist
|
|
Review Committee Chair
|
|
Strategic Architect
|
|
```
|
|
|
|
## 26. Related Skills
|
|
|
|
List Skills that execute or support the model.
|
|
|
|
Example:
|
|
|
|
```text
|
|
cognitive-imaging.skill.md
|
|
prediction-error-capture.skill.md
|
|
do-operator-test.skill.md
|
|
```
|
|
|
|
## 27. Runtime Usage
|
|
|
|
List Runtimes where the model participates.
|
|
|
|
Example:
|
|
|
|
```text
|
|
review-committee.runtime.md
|
|
modeling-committee.runtime.md
|
|
article-to-model-extraction.runtime.md
|
|
```
|
|
|
|
## 28. Examples
|
|
|
|
Include examples only when they clarify the model.
|
|
|
|
Avoid dumping long source excerpts.
|
|
|
|
Use short examples that show:
|
|
|
|
```text
|
|
Input
|
|
Model application
|
|
Output
|
|
Failure boundary
|
|
```
|
|
|
|
## 29. Evaluation Criteria
|
|
|
|
Define how to judge whether the model was applied well.
|
|
|
|
Examples:
|
|
|
|
```text
|
|
Did it identify a real mechanism rather than a surface pattern?
|
|
Did it define scope?
|
|
Did it avoid unfalsifiable explanation?
|
|
Did it preserve prediction-error discipline?
|
|
Did it produce a usable output?
|
|
```
|
|
|
|
## 30. Version Notes
|
|
|
|
Record:
|
|
|
|
```text
|
|
What changed
|
|
Why it changed
|
|
What remains unstable
|
|
What requires user review
|
|
```
|
|
|
|
## 31. Open Questions
|
|
|
|
Use this for:
|
|
|
|
```text
|
|
Naming uncertainty
|
|
Scope uncertainty
|
|
Overlaps with other models
|
|
Missing examples
|
|
Weak falsification boundary
|
|
Possible merge with another model
|
|
```
|
|
|
|
## 32. Model Card Quality Checklist
|
|
|
|
Before finalizing a Model Card, check:
|
|
|
|
```text
|
|
Does it preserve the model's original conceptual force?
|
|
Is the core problem clear?
|
|
Is the scope defined?
|
|
Is the mechanism explicit?
|
|
Are assumptions listed?
|
|
Are failure modes included?
|
|
Is the falsification boundary meaningful?
|
|
Are related agents and skills identified?
|
|
Is status marked correctly?
|
|
Is source material recorded?
|
|
```
|
|
|
|
## 33. Promotion Rules
|
|
|
|
A Model Card may move from `candidate` to `draft` when:
|
|
|
|
```text
|
|
The model is structurally clear.
|
|
Source material is known.
|
|
Scope and mechanism are present.
|
|
Failure modes are at least partly defined.
|
|
```
|
|
|
|
A Model Card may move from `draft` to `active` only when:
|
|
|
|
```text
|
|
The user confirms it.
|
|
The model name is accepted.
|
|
The scope is accepted.
|
|
The mechanism is accepted.
|
|
It has a meaningful falsification boundary.
|
|
It is properly indexed.
|
|
```
|
|
|
|
## 34. Merge Rules
|
|
|
|
Merge models when:
|
|
|
|
```text
|
|
Two models have the same mechanism.
|
|
One is clearly a renamed version of another.
|
|
The distinction is terminological rather than structural.
|
|
```
|
|
|
|
Do not merge when:
|
|
|
|
```text
|
|
They share vocabulary but solve different problems.
|
|
They share metaphor but have different mechanisms.
|
|
One is foundational and the other is applied.
|
|
```
|
|
|
|
## 35. Deprecation Rules
|
|
|
|
Deprecate a Model Card when:
|
|
|
|
```text
|
|
It is superseded by a better model.
|
|
It was extracted incorrectly.
|
|
It overlaps too much with a stronger model.
|
|
The user rejects it.
|
|
It no longer represents the user's thinking.
|
|
```
|
|
|
|
Do not delete deprecated models immediately.
|
|
|
|
Mark them as deprecated and explain why.
|
|
|
|
## 36. Final Rule
|
|
|
|
A Model Card is not a tombstone for an idea.
|
|
|
|
It is a living interface between thought, agents, skills, workflows, and future knowledge work.
|
|
|
|
It should make the model easier to use without making it shallower.
|
|
|