convez.ai
AgenteAutomaçãoAvançado
Haro3573

Cognitive Annotation Plugin

Haro3573/cognitive-annotation-plugin

Anotação cognitiva de transcrições com 4 agentes especializados

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin para Claude Code que analisa transcrições de conversas através de um pipeline de 4 agentes especializados em função executiva, metacognição, memória/raciocínio e modelo mental do usuário. Extrai evidências comportamentais com pontuação de confiança e explicações alternativas.

Instalação

$npx convez-ai Haro3573/cognitive-annotation-plugin

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Análise de entrevistas e conversas para pesquisa comportamental
  • Avaliação cognitiva de interações usuário-sistema
  • Documentação estruturada de padrões de raciocínio e tomada de decisão

Veredito

Ferramenta sofisticada e bem arquitetada para análise cognitiva profunda de transcrições, sem dependências externas. Excelente para pesquisadores e designers que precisam estruturar evidências comportamentais com rigor metodológico.

README

A tradução para o português deste README ainda está na fila.

cognitive-annotation

A Claude Code plugin that annotates conversation transcripts with cognitive behavioral evidence across four domains: executive function, metacognition, memory & reasoning, and user mental model.

Installation

This marketplace contains two plugins. Install both:

cognitive-annotation — the 4-agent annotation pipeline:

/plugin marketplace add Haro3573/cognitive-annotation-plugin
/plugin install cognitive-annotation

cognitive-agent — the real-time inline suggestion agent:

/plugin install cognitive-agent

(The marketplace add command only needs to run once; both plugins live in the same marketplace.)

Usage

Pass a file path:

/cognitive-annotation:annotate sample_conversation.json

Or paste a transcript directly into the conversation, then run:

/cognitive-annotation:annotate

If no transcript is provided, the plugin will ask you for one.

What it extracts

AgentExtracts
Executive FunctionPlanning behavior, inhibition behavior, shifting behavior
MetacognitionKnowledge of limits, confidence calibration, error monitoring, monitoring→control coupling
Memory & ReasoningDomain knowledge injection, deductive / inductive / abductive / analogical reasoning
User Mental ModelSystem model updates, cooperation and persuasion

Each extraction includes an evidence quote, turn index, confidence score (≥ 0.3), mundane alternative explanation, and reasoning for the label.

Output

A combined JSON object with one key per agent, plus a plain-language summary of notable findings.

{
  "executive_function": {
    "planning_behavior": [ ... ],
    "inhibition_behavior": [ ... ],
    "shifting_behavior": [ ... ],
    "null_findings": "..."
  },
  "metacognition": { ... },
  "memory_and_reasoning": { ... },
  "user_mental_model": { ... }
}

Empty sub-categories include a null_findings string explaining what was searched for and not found — a blank with explanation is more useful than a forced extraction.


System Architecture

Overview

The plugin is a pure Claude Code component — no Python, no API key, no external dependencies. It consists of one orchestrator skill and four specialized subagents.

User
 │
 │  /cognitive-annotation:annotate <transcript>
 ▼
┌─────────────────────────────────────────┐
│         SKILL: annotate                 │
│  (runs in main Claude Code thread)      │
│                                         │
│  1. Resolves transcript source          │
│  2. Spawns 4 subagents via Agent tool   │
│  3. Combines results into JSON          │
└────────┬────────┬────────┬──────────────┘
         │        │        │        │
         ▼        ▼        ▼        ▼
   ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
   │  A1  │ │  A2  │ │  A3  │ │  A4  │
   │ Exec │ │Meta- │ │Mem & │ │User  │
   │ Func │ │cogn. │ │Reas. │ │Model │
   └──────┘ └──────┘ └──────┘ └──────┘

Components

plugins/cognitive-annotation/skills/annotate/SKILL.md — the entry point. Runs in the main Claude Code conversation thread. Resolves the transcript (from a file path, inline text, or conversation context), then sequentially invokes each of the four subagents via the Agent tool, passing the full transcript in each call. Combines the four results into a single JSON structure.

plugins/cognitive-annotation/agents/*.md — four subagent definitions. Each runs in its own isolated context window with:

  • A specialized system prompt grounded in cognitive psychology theory
  • tools: [] — no file access; the transcript arrives entirely in the prompt
  • model: sonnet — Sonnet balances annotation depth with speed

Subagents are invoked sequentially (Claude Code subagents cannot run in parallel within a single session). Each returns a JSON object; the skill merges them.

Execution flow

1. /cognitive-annotation:annotate <path>
        │
2. Skill reads file at <path>
        │
3. Skill calls Agent tool → executive-function subagent
        │   subagent reasons over transcript
        │   returns { executive_function_behavior: { ... } }
        │
4. Skill calls Agent tool → metacognition subagent
        │   returns { metacognition_behavior: { ... } }
        │
5. Skill calls Agent tool → memory-reasoning subagent
        │   returns { memory_and_reasoning_behavior: { ... } }
        │
6. Skill calls Agent tool → user-mental-model subagent
        │   returns { user_mental_model_behavior: { ... } }
        │
7. Skill merges all four → combined JSON + summary

Annotation design principles

  • Liberal extraction: agents extract at confidence ≥ 0.3 and report their certainty honestly. False negatives are unrecoverable in a dataset; false positives can be filtered downstream.
  • Mundane alternative: every extraction requires a mundane alternative explanation. The cognitive label is kept only if the mundane reading is less plausible.
  • No schema-shape filling: agents are explicitly instructed not to produce one extraction per sub-category to satisfy schema shape. An honest zero with a specific null_findings explanation is more scientifically valuable than an invented extraction.
  • HUMAN turns only: all four agents annotate human turns exclusively. AI turns provide context but are not coded.

Relation to the Python SDK pipeline

This plugin is the Claude Code-native form of the same pipeline. A standalone Python version (Cognitive_Annotation/main.py) using the Claude Agent SDK runs the same four agents via asyncio.gather() for true parallel execution and writes structured output to results.json. Use the plugin for interactive annotation within Claude Code; use the Python pipeline for batch processing or automation.

Theoretical grounding

The four cognitive domains extracted by this plugin are derived from the Cognitive Taxonomy introduced in:

Burnell, R., Yamamori, Y., Firat, O., Olszewska, K., Hughes-Fitt, S., Kelly, O., Galatzer-Levy, I. R., Morris, M. R., Dafoe, A., Snyder, A. M., Goodman, N. D., Botvinick, M., & Legg, S. (2026). Measuring Progress Toward AGI: A Cognitive Framework. Google DeepMind. PDF

That paper deconstructs general intelligence into 10 cognitive faculties drawing from psychology, neuroscience, and cognitive science. The four agents in this plugin operationalize a subset of those faculties as annotation targets for human–AI conversation transcripts.

Each agent's extraction criteria are additionally grounded in the sub-field literature for its domain:

AgentPrimary theory
Executive FunctionUpdating / Inhibition / Shifting model (Miyake et al., 2000)
MetacognitionMonitoring and Control framework (Nelson & Narens, 1990)
Memory & ReasoningPeirce's inference types; Structure-Mapping Theory (Gentner, 1983)
User Mental ModelMental models of interactive systems (Norman, 1983)
Ver o original no GitHub

Bom para

Relacionados