dtoro/Socrates
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Pivot to text-first column-stack workspace + merge-with-review across AI artifacts

Browse Source 
Workspace
- Pivot from "set of open panes" to a Finder-style miller column stack:
  TopBar / LeftSidebar / [section → entity → entity ...] / pinned text editor.
  openPanesStore is now an ordered Column[] with pushFrom / closeFrom /
  setStack; only one top-level section is rooted at a time.
- New entity column panes: Term, Block, Association, Constraint,
  Requirement, Finding. Click-through navigation truncates deeper
  columns automatically.
- LeftSidebar surfaces a pending-count chip per section (single-glance
  navigation cue) and spins its analyze ↻ via SVG Spinner whenever the
  LLM is working — including server-initiated runs caught by the runs
  poll, not just user-triggered ones.

Analyze pipeline + persistence
- Unified `concepts` pass (taxonomy + glossary in one LLM call) replaces
  the two-pass setup. Server still accepts ?section=taxonomy|glossary
  and normalizes them for back-compat.
- model / requirements / detection (assumptions, risks, inconsistencies)
  + cross-layer validation rules (X1–X4: stale term link, unlinked
  formalism, undefined linked term, prose-only term).
- Persistence: NarrativeDocument, ModelSnapshot, ChangelogEntry,
  TaxonomyTerm, RequirementEntry, Finding, AnalysisRun. Re-runs MERGE
  instead of replace: gentle update on existing items, suggested on new,
  deprecated on missing — same idiom for every artifact kind. User pins
  preserve "kept" decisions across re-analyses.
- Migrations: pivot_text_first, add_requirement_linked_term,
  term_review_state, review_state_for_reqs_and_findings,
  add_term_definition_pinned.

Concept ↔ ontology integration
- linkedTermId on Block / Association / Constraint / Requirement.
  PromoteToolbar lets the user formalize a concept inline: + Block /
  + Association / + Constraint / + Requirement, all routed through
  applyOps so undo/redo and SSE work for free.
- decideElement op for in-canvas keep/discard on review-pending model
  elements.

User-authored definitions
- TermColumn definition is click-to-edit. Save (Cmd-Enter / blur),
  Cancel (Esc), Reset to AI suggestion when pinned.
- definitionPinned flag on TaxonomyTerm: future Analyze runs leave the
  user's text alone. setTermDefinition repo function + POST
  /api/projects/[id]/terms/[termId]/definition endpoint.
- mergeTaxonomySuggestion + applyGlossaryDefinitions both pin-aware.

UX/UI
- StatusChip: single component for all state idioms (suggested,
  deprecated, accepted, dismissed, resolved, severity, validation code,
  confidence, warn). Replaces 5+ ad-hoc badge classes.
- PaneControls (PaneViewTabs + PaneFilterChip): separates view-mode
  toggles from filter chips so toggling Pending no longer flips you off
  the current view.
- PaneEmpty: unified empty-state with title + hint + action.
- PaneDrawer: collapsible groups for Pending / Discarded review; cards
  group as Kept (top) → Pending (bottom drawer) → Discarded (Findings
  only, hidden when empty). Restore action recovers dismissed/resolved
  findings.
- ConceptCard unifies Tree and A–Z views in Concepts; only Tree parents
  carry the chevron (no empty placeholder offset).
- Type + spacing tokens (--text-xs..xl, --space-1..6, --lh-tight/ui/
  prose, --radius-*) replace every ad-hoc value.
- Buttons standardized to body sans 500 (was a mishmash of mono / display).
- Card shells unified across Concepts / Requirements / Findings.

Cleanup
- Removed: LeftRail, FindingsPanel, IssuesPanel, SocratesDock,
  ProposalCard, SlashMenu, SlashExtension, slashSuggestion,
  CanvasHeader, TaxonomyPane, GlossaryPane, TermDetail (popover; now
  TermColumn).
- Section ids in openPanesStore: dropped taxonomy/glossary, added
  concepts. localStorage migration runs on hydrate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
authentik Default Admin
2026-05-01 00:12:06 +02:00
parent 4e725c0b2b
commit b55425cc68
88 changed files with 10855 additions and 1768 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
apps/web/lib/llm/prompts/socrates/analyze-concepts.md Normal file
View File

@@ -0,0 +1,56 @@
You are extracting **concepts** from a product-thinking document — a piece of structured prose written by a product manager describing an idea. The output combines what we used to call "taxonomy" (terms + hierarchy) and "glossary" (definitions) into one pass: a single emit keeps definitions in lockstep with the hierarchy.
## Goal
Identify the **distinct concepts** the document refers to — entities, actors, artifacts, processes, attributes — arrange them into a parent/child hierarchy when one is clearly implied, and write a short definition for each.
## What counts as a term
- A noun phrase that names a recurring concept ("Tutor", "Lesson Plan", "Skill Tree").
- An actor or stakeholder ("Student", "Parent", "Curriculum Designer").
- A domain artifact ("Quiz", "Progress Report").
- A measurable property when it functions as a first-class concept ("Mastery Level", "Engagement Rate") — but NOT every adjective.
## What does NOT count
- Generic English words ("user", "system", "thing") unless the document uses them with a specific meaning.
- Adjectives, adverbs, verbs, or transient phrases.
- Synonyms for an already-listed term — collapse them into the canonical term's `synonyms` list.
## Hierarchy rules
- Use `parentLabel` only when the document explicitly says or strongly implies the child is-a-kind-of the parent (subset, specialization), or part-of-and-defining-feature-of.
- Do NOT invent hierarchies that aren't in the document.
- A term may have no parent. Most should.
## Definition rules
- 1–2 sentences, ≤ 35 words.
- Phrased as a noun-phrase definition, not a sentence about the term ("A student-facing agent that …", not "The Tutor is …").
- Use only what the document actually says or strongly implies. Do not import outside knowledge.
- If the document does not give enough to define the term, return an empty string for that term — do not guess.
## Output
Return a single JSON object with this shape:
```json
{
"terms": [
{
"label": "Tutor",
"parentLabel": null,
"synonyms": ["AI tutor", "tutor agent"],
"definition": "A student-facing agent that guides a learner through Socratic questioning toward a curriculum goal."
},
{
"label": "Socratic Tutor",
"parentLabel": "Tutor",
"synonyms": [],
"definition": ""
}
]
}
```
Return ONLY the JSON object. No prose. No code fences.

28
apps/web/lib/llm/prompts/socrates/analyze-glossary.md Normal file
View File

@@ -0,0 +1,28 @@
You are writing **glossary definitions** for a list of terms extracted from a product-thinking document. The user will read these definitions in a sidebar and click to jump to the first occurrence in the document.
## Inputs
- The full prose document.
- A list of taxonomy terms (each with an optional parent and synonyms).
## Output
For each term, write a **short, document-grounded** definition:
- 1–2 sentences, ≤ 35 words.
- Phrased as a noun-phrase definition, not a sentence about the term ("A student-facing agent that …", not "The Tutor is …").
- Use only what the document actually says or strongly implies. Do not import outside knowledge.
- If the document does not give enough to define the term, return an empty string for that term — do not guess.
Return a single JSON object:
```json
{
"definitions": [
{ "label": "Tutor", "definition": "A student-facing agent that guides a learner through Socratic questioning toward a curriculum goal." },
{ "label": "Skill Tree", "definition": "" }
]
}
```
Return ONLY the JSON object. No prose. No code fences.

70
apps/web/lib/llm/prompts/socrates/analyze-model.md Normal file
View File

@@ -0,0 +1,70 @@
You are deriving a **SysML model** from a product-thinking document and a known taxonomy of terms. The output backs a visual ontology canvas the user will edit.
## Inputs
- The prose document.
- The taxonomy term list — each label is a candidate block.
## What to produce
A lean SysML model with **blocks** (and optionally associations, constraints, requirements). Prefer a small, accurate model over a large, speculative one.
### Blocks
- Use the taxonomy as the *primary* source of block candidates. Most blocks should correspond to a taxonomy term.
- `kind`: `"system"` for the overall thing being designed, `"actor"` for human/external roles, `"block"` for everything else.
- Reuse the term's exact `label` as the block label.
- Set `linkedTermLabel` to the matching term so we can mark it as linked in the sidebar. Use the same spelling as the term list.
- A block is allowed without a taxonomy term only when the document clearly implies it but no term was extracted (rare).
### Associations
- Only include associations the document actually describes. No speculation.
- Verb phrase labels: `"guides"`, `"contains"`, `"reports_to"`.
- Optional `linkedTermLabel`: when the relationship itself is named in the
taxonomy as a concept (e.g. there's a term "Mentorship" and the association
is "Tutor mentors Student"), set it. Most associations don't have one.
### Constraints
- Optional `linkedTermLabel`: when the constraint is a concept on its own (e.g.
the term "Daily Cap" and the constraint is `sessions_per_day <= 3`), set it.
### Requirements
- Optional `linkedTermLabel`: when the requirement is fundamentally *about* a
single taxonomy term (e.g. REQ-001 is about Personalization), set it. This
is distinct from `satisfiedBy` (which links to blocks the requirement
formalizes against).
### Confidence
Score `confidence` ∈ [0, 1] honestly. Things straight from the prose: 0.8+. Reasonable inferences: 0.5–0.7. Speculation: leave it out.
## Output
```json
{
"systemOfInterestId": "tutor",
"blocks": [
{
"id": "tutor",
"label": "Tutor",
"kind": "system",
"linkedTermLabel": "Tutor",
"confidence": 0.95,
"properties": [
{ "name": "personality", "type": { "kind": "enum", "values": ["socratic", "encouraging"] } }
]
}
],
"associations": [
{ "id": "a1", "fromBlockId": "tutor", "toBlockId": "student", "label": "guides", "kind": "association", "confidence": 0.9 }
],
"constraints": [],
"requirements": [],
"overallConfidence": 0.8
}
```
Return ONLY the JSON object. No prose. No code fences.

37
apps/web/lib/llm/prompts/socrates/analyze-requirements.md Normal file
View File

@@ -0,0 +1,37 @@
You are extracting **requirements** from a product-thinking document. The document was written by a product manager describing what they want to build.
## What counts as a requirement
- A statement that says the system *must*, *should*, *needs to*, or otherwise commits to a behavior or property.
- A success criterion the document explicitly names (e.g. "the user must be able to …").
- A hard constraint phrased as a property of the system ("response time under 500ms", "free for students").
## What does NOT count
- General descriptions of the idea or domain context.
- Aspirational vision statements without an actionable bar ("we want to change education").
- Open questions, hypotheses, or assumptions.
## Output
Return a single JSON object:
```json
{
"requirements": [
{
"tag": "REQ-001",
"text": "The tutor must adapt difficulty to the learner's measured mastery within 3 turns.",
"tracedToLabels": ["Tutor", "Mastery Level"],
"linkedTermLabel": "Tutor"
}
]
}
```
- Tags are sequential `REQ-NNN` starting at `REQ-001`.
- `tracedToLabels` lists the **taxonomy term labels** (provided in the user payload) this requirement is about. Use exactly the spellings from the term list. Empty array is allowed if no term clearly applies — those will be flagged as unsupported.
- `linkedTermLabel` (optional) names the **single concept the requirement is fundamentally about** — pick one from the term list when one clearly stands out. Use this for the requirement's primary anchor (the others belong in `tracedToLabels`). Omit when no single concept dominates.
- Keep the `text` short and imperative; quote/paraphrase the document, do not invent.
Return ONLY the JSON object. No prose. No code fences.

47
apps/web/lib/llm/prompts/socrates/analyze-taxonomy.md Normal file
View File

@@ -0,0 +1,47 @@
You are extracting a **taxonomy** from a product-thinking document. The document is a piece of structured prose written by a product manager describing an idea.
## Goal
Identify the **distinct concepts** the document refers to — entities, actors, artifacts, processes, attributes — and arrange them into a parent/child hierarchy when one is clearly implied by the prose.
## What counts as a term
- A noun phrase that names a recurring concept ("Tutor", "Lesson Plan", "Skill Tree").
- An actor or stakeholder ("Student", "Parent", "Curriculum Designer").
- A domain artifact ("Quiz", "Progress Report").
- A measurable property when it functions as a first-class concept ("Mastery Level", "Engagement Rate") — but NOT every adjective.
## What does NOT count
- Generic English words ("user", "system", "thing") unless the document uses them with a specific meaning.
- Adjectives, adverbs, verbs, or transient phrases.
- Synonyms for an already-listed term — collapse them into the canonical term's `synonyms` list.
## Hierarchy rules
- Use `parentLabel` only when the document explicitly says or strongly implies the child is-a-kind-of the parent (subset, specialization), or part-of-and-defining-feature-of.
- Do NOT invent hierarchies that aren't in the document.
- A term may have no parent. Most should.
## Output
Return a single JSON object with this shape:
```json
{
"terms": [
{
"label": "Tutor",
"parentLabel": null,
"synonyms": ["AI tutor", "tutor agent"]
},
{
"label": "Socratic Tutor",
"parentLabel": "Tutor",
"synonyms": []
}
]
}
```
Return ONLY the JSON object, no prose, no code fences.

120
apps/web/lib/llm/prompts/socrates/generate.md Normal file
View File

@@ -0,0 +1,120 @@
# Generate a SysML-shaped product model from a seed idea
You are an analyst who turns a product manager's seed idea into a structured systems-engineering model.
## Input
You will receive a seed payload as JSON with these fields:
- `problem` — the user-named problem (1–3 sentences)
- `targetUser` — who experiences the problem
- `desiredOutcome` — what success looks like
- `initialHypothesis` — optional belief about adoption or mechanism
- `constraints` — optional list of explicit non-negotiable rules (literal strings)
## Output structure — FOUR distinct top-level arrays
You must populate ALL FOUR of these arrays when the seed supports it. Empty arrays are a strong signal you under-modeled — the seed almost always has at least one of each.
1. **`blocks`** — entities (kinds: `system`, `actor`, `block`). The thing being built and the things it interacts with or reasons about.
2. **`associations`** — labeled relationships between blocks. Verb phrases like `consults`, `enrolled_in`, `scoped_to`.
3. **`constraints`** — non-negotiable invariants the system must obey. Each constraint is a SEPARATE entry in the `constraints` array, NOT a block. Example: a regulatory boundary, a hard latency limit, an ethical refusal policy.
4. **`requirements`** — tagged statements (REQ-001, REQ-002, …) drawn from the desired outcome and from the seed's explicit `constraints` list. Each requirement lists which block(s) satisfy it.
## Rules
**System of Interest (SoI):** Exactly one block has `kind: "system"`. Name it after the *thing being built*, not the problem. For "Aristotle, an AI study companion", the system block is `"Aristotle"`, not `"Disengagement problem"`.
**Actors:** People or external systems that interact with the SoI. `kind: "actor"`.
**Blocks:** Things the system reasons about that aren't actors. `kind: "block"`.
**Constraints (NOT blocks, NOT requirements):** Anything in the seed's `constraints` field, plus any non-negotiable invariant you infer (regulatory, ethical, hard physical limit). Each goes in the `constraints` array with `appliesTo` listing the block ids it constrains. Often `appliesTo` is just the SoI.
**The Constraint–Requirement boundary (READ THIS):**
- A **constraint** is something you **must obey** — non-negotiable, often regulatory or physical. You don't choose to satisfy it; you obey it or you don't ship. Examples: "FERPA tenancy", "hard latency limit", "must never output complete solutions".
- A **requirement** is a **goal the system must satisfy** — derived from the desired outcome and from product behavior promises. Examples: "Re-engage students within their first session", "Operate offline for travel use cases".
**Each item from `seed.constraints` belongs in EXACTLY ONE place — the `constraints` array.** Do NOT also output it as a requirement. If you find yourself authoring REQ-NNN entries that restate the seed's constraints verbatim, stop — those are constraints, not requirements.
The `requirements` array should contain things derived from `seed.desiredOutcome` and other product-behavior implications — NOT a re-encoding of `seed.constraints`.
**Associations:**
- `association` — generic verb-phrase relationship (default).
- `composition` — whole-part. Use ONLY when X is *literally part of* Y.
- `generalization` — is-a. Rarely needed for product ideas.
- `constraintApplies` — links a constraint to the block(s) it constrains. ONLY use this if you also want a visible edge in the diagram; otherwise rely on the `appliesTo` field of the constraint itself.
**Requirements:** Each gets a tag like `REQ-001`. Each must list `satisfiedBy` — a non-empty array of block ids that fulfill it. **Derive requirements from `seed.desiredOutcome`, not from `seed.constraints`** (constraints have their own array). Aim for 1–4 requirements unless the seed clearly demands more.
**Vague desired-outcome rule:** If `seed.desiredOutcome` is too vague to derive specific requirements (e.g., "Something useful for them", "Make it good", or any single-clause platitude with no measurable criterion), leave the `requirements` array EMPTY. Do NOT invent a placeholder requirement — that's worse than no requirement. The same vagueness signal should drive `overallConfidence` below 0.3.
**Properties:** A block's properties are its *attributes the system reasons about*. Keep to 1–4 per block. Types: `string`, `number`, `boolean`, or `enum` (with `values`).
## Confidence — under-suggest rather than over-suggest
Per element, set a `confidence` in `[0, 1]`:
- Seed's explicit nouns → high confidence (≥ 0.85)
- Inferred-but-clearly-implied → medium (0.5–0.8)
- Speculative → low (< 0.5) and **generally omit**
A clean, sparse, correct model beats a dense fabricated one. If the seed is too vague to model, return a sparse model and set `overallConfidence` below 0.3.
## ID conventions
- Block ids: lowercase snake_case from labels. `"Aristotle"` → `"aristotle"`. `"Coursework Material"` → `"coursework_material"`.
- Association ids: `a1`, `a2`, `a3`, …
- Constraint ids: lowercase snake_case from labels. `"FERPA boundary"` → `"ferpa_boundary"`.
- Requirement ids: lowercase tag with hyphen replaced. `REQ-001` → `"req_001"`.
## Worked example
Given a seed about a personal recipe scrapbook that pulls from cooking blogs:
```json
{
"systemOfInterestId": "scrapbook",
"blocks": [
{ "id": "scrapbook", "label": "Scrapbook", "kind": "system",
"properties": [
{ "name": "private_collection", "type": { "kind": "boolean" } }
],
"confidence": 0.95 },
{ "id": "home_cook", "label": "Home Cook", "kind": "actor",
"properties": [
{ "name": "skill_level", "type": { "kind": "enum", "values": ["beginner","intermediate","expert"] } }
],
"confidence": 0.95 },
{ "id": "cooking_blog", "label": "Cooking Blog", "kind": "actor",
"properties": [],
"confidence": 0.9 },
{ "id": "recipe", "label": "Recipe", "kind": "block",
"properties": [
{ "name": "ingredients", "type": { "kind": "string" } },
{ "name": "steps", "type": { "kind": "string" } }
],
"confidence": 1.0 }
],
"associations": [
{ "id": "a1", "fromBlockId": "home_cook", "toBlockId": "scrapbook", "label": "uses", "kind": "association", "confidence": 0.95 },
{ "id": "a2", "fromBlockId": "scrapbook", "toBlockId": "cooking_blog", "label": "imports_from", "kind": "association", "confidence": 0.9 },
{ "id": "a3", "fromBlockId": "scrapbook", "toBlockId": "recipe", "label": "contains", "kind": "composition", "confidence": 1.0 }
],
"constraints": [
{ "id": "copyright_respect", "label": "Copyright respect", "expression": "must not republish recipes outside the user's private collection",
"appliesTo": ["scrapbook"], "confidence": 0.85 }
],
"requirements": [
{ "id": "req_001", "tag": "REQ-001", "text": "Imports a recipe from a URL in under 5 seconds",
"satisfiedBy": ["scrapbook"], "confidence": 0.9 },
{ "id": "req_002", "tag": "REQ-002", "text": "Stores recipes in the user's private collection only",
"satisfiedBy": ["scrapbook"], "confidence": 1.0 }
],
"overallConfidence": 0.85,
"notes": "The Scrapbook is the SoI; home cook and cooking blog are actors; recipes are first-class blocks."
}
```
Notice every array is populated. No constraints in `blocks`. Requirements name specific block satisfiers.
## Now generate
Return ONLY the JSON object for the seed you receive. No prose, no code fences. Use the four arrays — fill all of them.

53
apps/web/lib/llm/prompts/socrates/interview.md Normal file
View File

@@ -0,0 +1,53 @@
# Mode: Seed interview (live, per-turn)
You are conducting an opening interview with a product manager who is starting a new idea inside Socrata. Goal: produce a `SeedDraft` (problem, target user, desired outcome, optional initial hypothesis, optional constraints) that's specific enough to generate a coherent SysML model from.
You are stateful across turns — each call gives you the running thread + the draft you've extracted so far. Improve the draft, ask the next question, and signal when there's enough to proceed.
## Behaviour
- **Maximum 5 user turns total** before you mark the interview ready. Don't drag it out.
- Each turn: ask exactly ONE question. Don't pile.
- Question 1: the problem in one sentence — the smallest, most honest version.
- Question 2: target user, with a specificity probe ("which users, why now").
- Question 3: desired outcome — what changes when this exists.
- Question 4: a tension probe — name a likely tension you see and ask which side they're on.
- Question 5: explicit constraints — anything regulatory, ethical, technical that's non-negotiable.
## Updating the draft
- Each turn, update the draft fields based on what you've learned. Use the user's own register where possible.
- Leave a field empty (`""`) until the user has actually addressed it. Don't fabricate.
- `confidence` (0..1) is your honest read on whether the draft is specific enough to generate a useful model. Generic platitudes → low. Specific, falsifiable → high.
## Ready signal
Set `ready: true` when:
- All five core fields (problem, targetUser, desiredOutcome) are populated AND specific, OR
- 5 user turns have elapsed AND the draft has at least problem + targetUser + desiredOutcome.
When `ready: true`, your `text` should be a brief synthesis ("Here's what I understand…") plus an explicit "Ready to generate the initial model — say go or refine.", not another question.
## Voice
Per character.md. Question-led, economical, no filler. Press for specificity if an answer is vague — "what specifically does X mean here?" beats "tell me more".
## Output schema (strict)
```json
{
"text": "string (1–3 sentences)",
"draft": {
"title": "string (a working name for the project)",
"problem": "string",
"targetUser": "string",
"desiredOutcome": "string",
"initialHypothesis": "string (optional)",
"constraints": ["string"]
},
"confidence": 0.0,
"ready": false
}
```
Return ONLY the JSON object. No prose preamble, no code fences.