@synap-core/workspace-templates 0.7.1 → 0.7.3

package/src/research-base.yaml

@@ -0,0 +1,516 @@
+# Research workspace template — the agnostic research substrate
+# ============================================================================
+# This is the BASE of the research family: the data model + the knowledge map +
+# the one universal playbook that turns a question into a fully-recorded
+# investigation. It is domain-agnostic on purpose — a physicist, a founder doing
+# market research, and someone learning a subject all use the SAME kinds
+# (field / concept / source / hypothesis / finding) and the SAME graph.
+#
+# The design commitment: store the research PROCESS, not just the answer. Every
+# source the agent considered is kept and ranked (rejected ones carry a reason —
+# nothing is silently dropped); every hypothesis, its supporting AND
+# contradicting evidence, and the reasoning are first-class linked entities. The
+# reasoning-STYLE recipes (decision analysis, literature review, …) ship as thin
+# OVERLAY templates that `compose` onto this base and add their own playbooks —
+# so a user installs the substrate once and adds whichever methods they want.
+#
+# Reuses the pod-wide `question` and `research` kinds so an investigation started
+# here lands where every other workspace already looks.
+
+meta:
+  slug: research-base
+  domain: knowledge
+  name: Research
+  description: A research substrate — turn a question into a fully-recorded investigation. Sources ranked (nothing dropped), hypotheses weighed, findings mapped onto a living graph of fields and concepts.
+  icon: microscope
+  color: "#8B5CF6"
+  tags: [research, knowledge, graph, sources, evidence, learning]
+  isPublic: true
+
+workspace:
+  name: Research
+  description: Turn a question into a fully-recorded investigation — sources ranked, hypotheses weighed, findings mapped onto a living graph of fields and concepts.
+  subtype: research-base
+  visibility: pod_visible
+  capabilities:
+    - research.graph
+    - research.sources
+  sourceRoles:
+    research: provider
+
+profiles:
+  # ── Reused pod-wide kinds (declared minimally so views/links resolve) ───────
+  # The pod already seeds `question` and `research` as KINDS (the default); the
+  # applier SKIPS properties that already exist, so these declarations exist only
+  # to make the SLUG declarable here (the validator resolves view scopes and
+  # entityLink endpoints against this template's `profiles`) and to reuse the
+  # existing pod-wide row. They MUST be declared as plain kinds to match how the
+  # pod seeds them — declaring them as facet-roles conflicts with the existing
+  # kind, the resolver SKIPS them on that mismatch, and the views/links scoped to
+  # `question`/`research` then throw at provisioning. Enums mirror the live
+  # pod-wide ones exactly.
+  - slug: question
+    displayName: Question
+    icon: help-circle
+    color: blue
+    description: An open question driving an investigation — the thing research answers.
+    properties:
+      - slug: questionStatus
+        label: Status
+        valueType: string
+        inputType: select
+        enumValues: [open, exploring, answered, abandoned]
+        constraints: { defaultValue: open }
+
+  - slug: research
+    displayName: Research
+    icon: microscope
+    color: violet
+    description: An investigation — the sources consulted, the findings, the confidence, and the conclusion.
+    # A plain kind, same as `question` above — declared to match how the pod seeds it.
+    properties:
+      - slug: researchStatus
+        label: Status
+        valueType: string
+        inputType: select
+        enumValues: [ongoing, concluded, abandoned]
+        constraints: { defaultValue: ongoing }
+      - slug: conclusion
+        label: Conclusion
+        valueType: string
+        inputType: textarea
+      - slug: researchConfidence
+        label: Confidence
+        valueType: string
+        inputType: select
+        enumValues: [low, medium, high]
+
+  # ── The cartography layer — fields & concepts ───────────────────────────────
+  # The "big things that overlap and link". A field is a domain (Mathematics, AI,
+  # Philosophy); a concept is an atomic idea inside one or more fields. Their
+  # edges (part_of / overlaps_with / prerequisite_of) ARE the knowledge map.
+  - slug: field
+    displayName: Field
+    icon: layers
+    color: indigo
+    description: A domain of knowledge — Mathematics, Physics, AI, Philosophy. Fields overlap and feed each other.
+    properties:
+      - slug: description
+        label: Description
+        valueType: string
+        inputType: textarea
+      - slug: aliases
+        label: Also known as
+        valueType: array
+        inputType: tags
+
+  - slug: concept
+    displayName: Concept
+    icon: lightbulb
+    color: amber
+    description: An atomic idea — Bayesian inference, gradient descent, qualia. Belongs to one or more fields; has prerequisites.
+    properties:
+      - slug: definition
+        label: Definition
+        valueType: string
+        inputType: textarea
+      - slug: aliases
+        label: Also known as
+        valueType: array
+        inputType: tags
+
+  # ── The evidence layer — sources, hypotheses, findings ──────────────────────
+  # `source` is the "rank by quality, lose nothing" primitive: every artifact the
+  # agent consulted is kept, banded for credibility, and marked cited / considered
+  # / rejected (rejected carries a reason). The rejected pile is part of the work.
+  - slug: source
+    displayName: Source
+    icon: file-text
+    color: cyan
+    description: Anything consulted — a paper, article, dataset, or post. Ranked by credibility and NEVER discarded; rejected sources are kept with a reason.
+    properties:
+      - slug: url
+        label: URL
+        valueType: string
+        inputType: url
+      - slug: author
+        label: Author
+        valueType: string
+        inputType: text
+      - slug: publishedAt
+        label: Published
+        valueType: date
+        inputType: date
+      - slug: sourceType
+        label: Type
+        valueType: string
+        inputType: select
+        enumValues: [paper, article, book, dataset, blog, video, forum, other]
+        constraints: { defaultValue: article }
+      - slug: credibilityBand
+        label: Credibility
+        valueType: string
+        inputType: select
+        enumValues: [high, medium, low, unknown]
+        constraints: { defaultValue: unknown }
+      - slug: qualityScore
+        label: Quality (0–100)
+        valueType: number
+        inputType: number
+        constraints: { min: 0, max: 100 }
+      - slug: status
+        label: Status
+        valueType: string
+        inputType: select
+        enumValues: [cited, considered, rejected]
+        constraints: { defaultValue: considered }
+      - slug: whyRejected
+        label: Why rejected
+        valueType: string
+        inputType: textarea
+      - slug: retrievedAt
+        label: Retrieved
+        valueType: date
+        inputType: date
+
+  - slug: hypothesis
+    displayName: Hypothesis
+    icon: git-branch
+    color: violet
+    description: A candidate theory or answer under test — argued for and against by sources.
+    properties:
+      - slug: statement
+        label: Statement
+        valueType: string
+        inputType: textarea
+      - slug: stance
+        label: Stance
+        valueType: string
+        inputType: select
+        enumValues: [proposed, supported, contested, refuted, superseded]
+        constraints: { defaultValue: proposed }
+      - slug: confidence
+        label: Confidence
+        valueType: string
+        inputType: select
+        enumValues: [low, medium, high]
+      - slug: reasoning
+        label: Reasoning
+        valueType: string
+        inputType: textarea
+
+  - slug: finding
+    displayName: Finding
+    icon: check-circle
+    color: "#10B981"
+    description: A validated fact — the thing established between the question, the sources, and the reasoning. Carries calibrated confidence and links to its evidence.
+    properties:
+      - slug: claim
+        label: Claim
+        valueType: string
+        inputType: textarea
+      - slug: confidence
+        label: Confidence (0–1)
+        valueType: number
+        inputType: number
+        constraints: { min: 0, max: 1 }
+      - slug: evidenceSummary
+        label: Evidence summary
+        valueType: string
+        inputType: textarea
+      - slug: status
+        label: Status
+        valueType: string
+        inputType: select
+        enumValues: [validated, provisional, retracted]
+        constraints: { defaultValue: provisional }
+
+views:
+  # The signature view — the living knowledge map. Fields and concepts and what
+  # we've established about them, as one navigable graph.
+  - name: Knowledge Map
+    slug: research-knowledge-map
+    type: graph
+    scopeProfileSlugs: [field, concept, finding]
+    description: The cartography — fields and concepts, their overlaps and prerequisites, and the findings attached to them.
+    defaultView: true
+    config:
+      layout: force
+      showRelations: true
+  # The daily driver — what still needs answering.
+  - name: Open Questions
+    slug: research-open-questions
+    type: list
+    scopeProfileSlug: question
+    description: Questions still open — the research backlog.
+    config:
+      filterBy: { field: questionStatus, operator: is, value: open }
+  # The evidence surface, ranked. Nothing is hidden — rejected sources show here
+  # too, with their reason.
+  - name: Sources
+    slug: research-sources
+    type: table
+    scopeProfileSlug: source
+    description: Every source consulted, ranked by credibility — including the ones that were considered and rejected.
+    config:
+      columns: [title, sourceType, credibilityBand, qualityScore, status]
+  - name: Hypotheses
+    slug: research-hypotheses
+    type: kanban
+    scopeProfileSlug: hypothesis
+    groupBy: stance
+    description: Candidate theories, grouped by where the evidence has left them.
+    config:
+      groupBy: stance
+  - name: Findings
+    slug: research-findings
+    type: table
+    scopeProfileSlug: finding
+    description: What's been established, with its confidence.
+    config:
+      columns: [title, confidence, status]
+  - name: Research Log
+    slug: research-log
+    type: table
+    scopeProfileSlug: research
+    description: Every investigation and where it stands.
+    config:
+      columns: [title, researchStatus, researchConfidence]
+
+# Schema-level relations — the epistemic predicates. Novel `type`s auto-create
+# their relation-defs on provisioning, so the graph and the relation picker have
+# domain-specific edges from day one.
+entityLinks:
+  # Cartography edges
+  - {
+      sourceProfileSlug: field,
+      targetProfileSlug: field,
+      type: overlaps_with,
+      label: Overlaps with,
+    }
+  - {
+      sourceProfileSlug: concept,
+      targetProfileSlug: field,
+      type: part_of,
+      label: Part of,
+    }
+  - {
+      sourceProfileSlug: concept,
+      targetProfileSlug: concept,
+      type: prerequisite_of,
+      label: Prerequisite of,
+    }
+  - {
+      sourceProfileSlug: concept,
+      targetProfileSlug: concept,
+      type: relates_to,
+      label: Relates to,
+    }
+  # Investigation edges
+  - {
+      sourceProfileSlug: research,
+      targetProfileSlug: question,
+      type: investigates,
+      label: Investigates,
+    }
+  - {
+      sourceProfileSlug: hypothesis,
+      targetProfileSlug: question,
+      type: answers,
+      label: Answers,
+    }
+  - {
+      sourceProfileSlug: research,
+      targetProfileSlug: source,
+      type: explored,
+      label: Explored,
+    }
+  - {
+      sourceProfileSlug: research,
+      targetProfileSlug: finding,
+      type: concluded,
+      label: Concluded,
+    }
+  # Evidence edges
+  - {
+      sourceProfileSlug: source,
+      targetProfileSlug: hypothesis,
+      type: supports,
+      label: Supports,
+    }
+  - {
+      sourceProfileSlug: source,
+      targetProfileSlug: hypothesis,
+      type: contradicts,
+      label: Contradicts,
+    }
+  - {
+      sourceProfileSlug: source,
+      targetProfileSlug: source,
+      type: cites,
+      label: Cites,
+    }
+  - {
+      sourceProfileSlug: finding,
+      targetProfileSlug: research,
+      type: derived_from,
+      label: Derived from,
+    }
+  - {
+      sourceProfileSlug: finding,
+      targetProfileSlug: source,
+      type: supported_by,
+      label: Supported by,
+    }
+  - {
+      sourceProfileSlug: finding,
+      targetProfileSlug: concept,
+      type: about,
+      label: About,
+    }
+
+# The one universal playbook — bound to `question`, so any question can launch it
+# from its detail page (see actionPlacements) or auto-match as a session. It runs
+# the full method: gather + rank sources (keep the rejects), form and weigh
+# hypotheses, emit findings with honest confidence, and place them on the map.
+playbooks:
+  - name: Research a Question
+    description: Investigate a question end-to-end — gather and rank sources (keeping the rejected ones), weigh hypotheses, emit findings with calibrated confidence, and map them onto the knowledge graph.
+    goalTemplate: >-
+      Investigate the question {question} and record the WHOLE investigation, not
+      just the answer. Steps: (1) Use the source-triage skill to gather sources
+      widely via web search, classify each by type and credibility, and create a
+      `source` entity for every one — including the ones you rejected, marked
+      rejected with a reason (never silently drop a source). (2) Form the
+      candidate answers as `hypothesis` entities and link each to the question;
+      link every source that bears on a hypothesis with `supports` or
+      `contradicts`. (3) Use the evidence-synthesis skill to weigh the supporting
+      vs contradicting sources and emit `finding` entities with honestly
+      calibrated confidence, each `supported_by` its sources and `derived_from`
+      this research. (4) Use the concept-cartography skill to place the findings
+      onto the knowledge map — resolve or create the `field`/`concept` entities
+      and wire `about` / `part_of` / `overlaps_with` / `prerequisite_of` edges,
+      deduping against what already exists. (5) Create the `research` entity that
+      `investigates` the question and `explored` the sources, write its
+      conclusion and confidence, and set the question's status to answered. Every
+      write is proposal-gated and reviewable.
+    subjectProfile:
+      profileSlug: question
+    params:
+      - { name: question, type: entity, label: Question, required: true }
+    executor: is-agent
+    grants:
+      - source-triage
+      - evidence-synthesis
+      - concept-cartography
+      - exa_search
+      - entity.create
+    status: active
+
+# A "Research this" action on every question's detail page — the entity is the
+# starter of the flow, exactly as designed.
+actionPlacements:
+  - profileSlug: question
+    surface: entity-detail
+    kind: playbook
+    ref: "Research a Question"
+    label: "Research this"
+
+# Web search via Exa (source gathering) + the research method skills. The user
+# connects Exa once on install; a missing key fails gracefully — the agent can
+# still reason over provided/pod sources.
+integrations:
+  - templateKey: research-methods
+  - templateKey: exa
+
+onboarding:
+  goal: >
+    Seed the workspace with the first real questions worth researching and the
+    fields they live in — so the agent has something concrete to investigate, not
+    a blank graph.
+  framing: |
+    THE RESEARCH LEAD: Act as a sharp research lead who cares about the QUESTION
+    being well-formed and the EVIDENCE being honest. A vague question ("learn
+    about AI") produces vague research; push for a question with a real edge — one
+    a good answer would actually change. And insist the work keeps its
+    counter-evidence: research that only kept what agreed with it isn't research.
+  expertise:
+    starters:
+      - >
+        A researchable question names what would count as an answer. "Is X better
+        than Y for Z?" beats "tell me about X" — the first has a shape the
+        evidence can fill; the second is a topic, not a question.
+      - >
+        Name the field(s) the question lives in up front — even roughly. It's the
+        first anchor on the map, and it's what lets the system later surface the
+        neighbouring field you didn't think to look in.
+    blindSpots:
+      - >
+        The most valuable sources are often the ones that DISAGREE. If the founder
+        only wants confirmation, say plainly that a one-sided answer is a weaker
+        answer — the method keeps both sides on purpose.
+      - >
+        "I already know the answer" is where research quietly stops being
+        research. If the conclusion is decided before the sources are gathered,
+        flag it — the point is to be able to be wrong.
+  collect:
+    - profileSlug: question
+      what: The first real questions worth investigating — each with a genuine edge, not a topic.
+      cardinality: few
+      keyFields: [questionStatus]
+    - profileSlug: field
+      what: The fields these questions live in — the first anchors on the knowledge map.
+      cardinality: few
+      keyFields: [description]
+  openingQuestions:
+    - "What's a question you actually want a well-evidenced answer to — one where a good answer would change what you do?"
+    - "Which field(s) does it sit in — and is there a neighbouring field it might borrow from?"
+    - "What would count as a convincing answer, and what would change your mind?"
+  doneWhen: >
+    At least one well-formed question captured with its field(s) anchored on the
+    map, ready for the Research a Question playbook to run against.
+
+app:
+  kind: stored
+  cellKey: entity-detail
+
+layout:
+  defaultView: Knowledge Map
+  defaultApp: null
+  pinnedApps: [dashboard, data, chat]
+  sidebarItems:
+    - kind: view
+      viewName: Knowledge Map
+      label: Map
+      icon: layers
+    - kind: view
+      viewName: Open Questions
+      label: Questions
+      icon: help-circle
+    - kind: view
+      viewName: Sources
+      label: Sources
+      icon: file-text
+    - kind: view
+      viewName: Findings
+      label: Findings
+      icon: check-circle
+    - kind: app
+      appId: data
+      label: Data
+      icon: database
+
+bento:
+  # Its own view row (distinct name from the embedded views, per the
+  # meetings-knowledge note — a shared name collides in the switcher).
+  viewName: Research Home
+  blocks:
+    - kind: view
+      viewName: Knowledge Map
+      pos: { x: 0, y: 0, w: 8, h: 6 }
+    - kind: view
+      viewName: Open Questions
+      pos: { x: 8, y: 0, w: 4, h: 3 }
+    - kind: view
+      viewName: Findings
+      pos: { x: 8, y: 3, w: 4, h: 3 }

package/src/research-decision.yaml

@@ -0,0 +1,158 @@
+# Decision Analysis overlay — a reasoning-STYLE that composes onto research-base
+# ============================================================================
+# One reasoning model, shipped as a thin overlay: IBIS (Issue → Positions →
+# Arguments). It adds the "Decision Analysis" playbook + the decision-specific
+# links to the SAME research substrate — it does NOT create a second workspace.
+# `dependencies: [{ slug: research-base, relation: compose }]` layers this
+# additively onto the research-base workspace (installing base first if absent).
+#
+# This is the pattern for the whole reasoning-model family: make each style its
+# own overlay file (decision, literature-review/Toulmin, competitive scan,
+# study-a-subject) and let the user compose whichever ones they want onto the one
+# base. Here we ship the decision style — the one that fits "weigh option A vs B
+# with the evidence, and keep why the loser lost".
+
+meta:
+  slug: research-decision
+  domain: knowledge
+  name: Decision Analysis
+  description: Turn an open question into a decision — options weighed with evidence, and the roads-not-taken preserved with the reasons they lost. Composes onto the Research substrate.
+  icon: scale
+  color: "#F59E0B"
+  tags: [research, decision, ibis, analysis, evidence]
+  isPublic: true
+
+workspace:
+  name: Research
+  description: Adds the IBIS decision-analysis method to the Research substrate — weigh options with evidence and record the decision, not just the winner.
+  subtype: research-base
+
+# Layer additively onto the research-base workspace (no second workspace).
+dependencies:
+  - slug: research-base
+    relation: compose
+    reason: Decision Analysis is a research method — it needs the Research substrate (question / source / hypothesis / finding) to work over.
+
+profiles:
+  # Slugs this overlay references in its links / views / playbook must be
+  # declared here for the per-file validator (base owns their full schema; the
+  # applier skips already-existing properties). Enums mirror the pod-wide defs.
+  - slug: question
+    displayName: Question
+    icon: help-circle
+    color: blue
+    description: The open question being decided.
+    # Pod-wide `question` is a first-class KIND (Decision 1 — the manifest retired
+    # w4.convert.question to a keep no-op). Declared as a plain kind to match the
+    # seed + research-base and reuse the existing pod-wide row.
+    properties:
+      - slug: questionStatus
+        label: Status
+        valueType: string
+        inputType: select
+        enumValues: [open, exploring, answered, abandoned]
+        constraints: { defaultValue: open }
+
+  - slug: hypothesis
+    displayName: Option
+    icon: git-branch
+    color: violet
+    description: A candidate option under consideration — argued for and against by sources.
+    properties:
+      - slug: stance
+        label: Stance
+        valueType: string
+        inputType: select
+        enumValues: [proposed, supported, contested, refuted, superseded]
+        constraints: { defaultValue: proposed }
+
+  - slug: decision
+    displayName: Decision
+    icon: scale
+    color: amber
+    description: A resolved decision — the recommendation, why it won, and the alternatives that lost (and why).
+    # Pod-wide `decision` is a first-class KIND (Decision 1 — w4.convert.decision
+    # retired to a keep no-op). Declared as a plain kind to match the seed; the
+    # `resolves` / `considered_in` links resolve against the reused pod-wide row.
+    properties:
+      - slug: summary
+        label: Summary
+        valueType: string
+        inputType: text
+      - slug: rationale
+        label: Rationale
+        valueType: string
+        inputType: textarea
+      - slug: alternatives
+        label: Alternatives considered
+        valueType: string
+        inputType: textarea
+      - slug: decisionStatus
+        label: Status
+        valueType: string
+        inputType: select
+        enumValues: [proposed, accepted, superseded, rejected]
+        constraints: { defaultValue: proposed }
+
+views:
+  - name: Decisions
+    slug: research-decisions
+    type: table
+    scopeProfileSlug: decision
+    description: Every decision reached, its recommendation, and where it stands.
+    config:
+      columns: [title, summary, decisionStatus]
+
+entityLinks:
+  - {
+      sourceProfileSlug: decision,
+      targetProfileSlug: question,
+      type: resolves,
+      label: Resolves,
+    }
+  - {
+      sourceProfileSlug: hypothesis,
+      targetProfileSlug: decision,
+      type: considered_in,
+      label: Considered in,
+    }
+
+playbooks:
+  - name: Decision Analysis
+    description: Structure an open question as a decision via IBIS — enumerate the options, argue each with evidence (keeping the rejected sources), weigh against explicit criteria, and record the decision with its roads-not-taken.
+    goalTemplate: >-
+      Analyze the question {question} as a DECISION and record the reasoning, not
+      just the verdict, using the ibis-decision-analysis skill. Steps: (1) State
+      the issue sharply so the options are genuinely mutually exclusive. (2)
+      Enumerate the real options — including the status-quo — as `hypothesis`
+      entities linked to the question, and to the resulting decision via
+      `considered_in`. (3) For each option, gather the sources that `supports` and
+      those that `contradicts` it (use source gathering; KEEP the rejected
+      sources with a reason — never drop the counter-evidence). (4) Weigh the
+      options against explicit, named criteria (cost, reversibility, risk, time,
+      evidence strength). (5) Record the recommendation as a `decision` entity
+      that `resolves` the question — its rationale explains why it won, and its
+      `alternatives` field preserves the options that lost and WHY. (6) Note what
+      evidence would change the decision. Every write is proposal-gated.
+    subjectProfile:
+      profileSlug: question
+    params:
+      - { name: question, type: entity, label: Question, required: true }
+    executor: is-agent
+    grants:
+      - ibis-decision-analysis
+      - source-triage
+      - exa_search
+      - entity.create
+    status: active
+
+actionPlacements:
+  - profileSlug: question
+    surface: entity-detail
+    kind: playbook
+    ref: "Decision Analysis"
+    label: "Analyze as decision"
+
+integrations:
+  - templateKey: research-methods
+  - templateKey: exa