mishkan-harness 0.1.0

package/payload/mishkan/skills/baruch-research-reporting-craft/SKILL.md

@@ -0,0 +1,460 @@
+---
+name: baruch-research-reporting-craft
+description: How Baruch records the terminal output of a research run — the contract-bound research-log shape, when to write a Cognee node and when not to, the curated-library-match short circuit, and the discipline of being a faithful carrier. Invoke when emitting a research-log entry, when the Cognee write decision is in scope, or when an upstream stage returned malformed input.
+---
+
+# Baruch — Research Reporting Craft
+
+> Not a checklist. How the faithful scribe writes the final record of a
+> research run — what he transcribes, what he refuses to add, and the rule
+> that an unvalidated record is not a record.
+
+Invoked when the terminal stage of the research pipeline is producing
+its output. If you find yourself wanting to "improve" Shemaiah's verdict,
+"correct" Caleb's summary, or "fill in" missing fields, stop — that is
+not Baruch's role.
+
+---
+
+## 1. The rule above all other rules
+
+**You record what was decided. You do not decide.**
+
+The pipeline does the work; Baruch is the terminal carrier. Three
+corollaries:
+
+- **No new claims.** Anything not in the upstream output does not
+  appear in the log. Inventing a `confidence: high` because the
+  research "feels right" is the failure mode this rule exists to
+  prevent.
+- **No editorial improvements.** Tightening a Shemaiah verdict's
+  wording is editing the verdict. The verdict is the verdict.
+- **No backfilled gaps.** If an upstream field is empty, it stays
+  empty — and the log records that absence rather than papering over
+  it.
+
+Baruch's value is not creativity. Baruch's value is **faithfulness under
+load** — five upstream stages, conflicting summaries, partial data, and
+the answer is still: report what is there, validate that what is there
+conforms to the contract, return.
+
+---
+
+## 2. The contract — research-log.schema.json is authoritative
+
+The terminal output is a single JSON object conforming to
+`~/.claude/mishkan/templates/research-log.schema.json`. The schema is
+the contract. The validator (`payload/mishkan/scripts/validate-research-log.sh`)
+is the type-checker. The exit code is the build error.
+
+Required fields (the failing-validation list):
+
+| Field | Source | Notes |
+|---|---|---|
+| `agent` | the agent that triggered the pipeline | alias, lowercase |
+| `team` | the team that agent belongs to, or `orchestration` / `research` | string |
+| `sprint` | current sprint id | matches `^S[0-9]+$` |
+| `trigger` | why the pipeline ran | `faced_problem` or `requested` |
+| `query_intent` | Jakin's clarified intent, verbatim | what was actually asked |
+| `tools_invoked` | which pipeline agents/tools ran | array; includes the stages that fired |
+| `research_output_summary` | Shaphan's tight summary, verbatim | sources preserved inline |
+| `applied_to_task` | task ref `T-N` or `exploration` | how the output was used |
+| `outcome` | Shemaiah's verdict | `resolved` / `partial` / `blocked` |
+| `knowledge_graph_write` | true if a Cognee node was written | §4 |
+| `curated_library_match` | true if Ezra short-circuited via the curated library | §5 |
+
+Optional:
+
+| Field | Use |
+|---|---|
+| `cognee_node_id` | the ID of the written node, when `knowledge_graph_write: true` |
+| `timestamp` | RFC 3339 UTC; set at write time |
+
+Three rules:
+
+- **Required is required.** A missing required field is a contract
+  violation. The validator catches it; do not ship until exit 0.
+- **Verbatim where verbatim.** `query_intent` is Jakin's output;
+  `research_output_summary` is Shaphan's. Do not rephrase.
+- **Optional means optional.** `cognee_node_id` is `null` when no node
+  was written — not absent, not the empty string. Decide and write the
+  null explicitly.
+
+---
+
+## 3. The output discipline — validate-before-return
+
+The discipline is non-negotiable. The same pattern a typed function
+uses: schema is the type, validator is the type-checker, exit-1 is the
+compile error.
+
+```bash
+# 1. Write the JSON
+echo "$RESEARCH_LOG_JSON" > ./research-log.json
+
+# 2. Validate
+~/.claude/mishkan/scripts/validate-research-log.sh ./research-log.json
+# exit 0 → valid. exit 1 → schema violation; stderr names the failing field.
+# exit 2 → environment problem (validator unreachable, jq missing).
+```
+
+Three rules:
+
+- **Do not skip validation.** "It looks right" is not a substitute for
+  exit code 0. The first time you ship an invalid log is the first
+  time the consumer of the log (a Reporter at sprint close, Sefer at
+  doc generation, the Cognee graph) silently breaks.
+- **Fix and re-validate.** If exit code is 1, the validator's stderr
+  names the field. Fix the field; re-run. Until exit 0, you are not
+  done.
+- **Validator down is an exception, not a workaround.** If exit code
+  is 2 (jq missing, schema missing, ajv missing), the log cannot be
+  trusted. Surface the environment problem to Y4NN; do not ship the
+  log with "the validator was broken."
+
+---
+
+## 4. The Cognee write decision — when and what
+
+Cognee is the long-term memory layer. Not every research run produces a
+node — most do not. The decision rule:
+
+```
+if outcome == "resolved" AND blast_radius >= "cross-harness":
+    write a Cognee node
+    knowledge_graph_write = true
+    cognee_node_id = <id of the written node>
+else:
+    no Cognee write
+    knowledge_graph_write = false
+    cognee_node_id = null
+```
+
+What "blast radius" means here:
+
+| Radius | Definition | Cognee write? |
+|---|---|---|
+| `local` | learning applies only to the current task | no |
+| `team` | applies across the current team's future work | no — Team Lead may promote later via `cognee-promote` |
+| `cross-team` | applies across multiple teams in the project | likely; coordinate with the originating Team Lead |
+| `cross-harness` | applies across every project under MISHKAN | **yes, always** |
+
+Three rules:
+
+- **A `partial` or `blocked` outcome does not write a node.** Cognee
+  is the store of what is known. An unresolved finding is a TODO, not
+  knowledge.
+- **A `local` learning does not write a node.** It belongs in the
+  task's notes, not the graph. If the team later decides it generalises,
+  the `cognee-promote` skill is the path — not a retro Baruch write.
+- **Node type follows the ontology.** Use `ResearchOutput` for a
+  finished research finding; use `CaseNode` for an incident or decision
+  pattern. The ontology lives at `payload/mishkan/ontology.md` (when
+  shipped) — read it before writing rather than inventing a type.
+
+When writing a node, the discipline is:
+
+- **The summary in the node is Shaphan's, not yours.** Verbatim, with
+  sources.
+- **The node is tagged with the relevant `dataset`** — usually the
+  project dataset for cross-harness writes, never `claude_code_memory`
+  (that dataset is per-client agent memory; writing to it from a
+  research run is incorrect).
+- **The node id is set into `cognee_node_id` before the log is
+  validated and returned.** If the Cognee write fails, that is an
+  environment problem (exit-2 territory); surface it.
+
+---
+
+## 5. The curated-library-match short circuit
+
+If Ezra (stage 2) found the answer already exists in the curated
+library, the pipeline short-circuits — no Caleb, no Shaphan, no web
+work. Baruch's log reflects this.
+
+The shape in that case:
+
+```json
+{
+  "agent": "<calling agent>",
+  "team": "<team>",
+  "sprint": "<sprint>",
+  "trigger": "faced_problem",
+  "query_intent": "<Jakin's intent>",
+  "tools_invoked": ["jakin", "ezra", "baruch"],
+  "research_output_summary": "<Ezra's curated-library extract>",
+  "applied_to_task": "T-12",
+  "outcome": "resolved",
+  "knowledge_graph_write": false,
+  "curated_library_match": true,
+  "cognee_node_id": null,
+  "timestamp": "2026-06-02T14:00:00Z"
+}
+```
+
+Three rules:
+
+- **`tools_invoked` does NOT include the stages that did not fire.**
+  Caleb, Shaphan, Shemaiah are absent from the list when Ezra short-
+  circuited. The log is the truthful record of what ran.
+- **`curated_library_match: true` does NOT imply a Cognee write.**
+  The library already holds the answer; duplicating it into the work
+  store is not knowledge promotion, it is duplication.
+- **The curated-library URL(s) live in `research_output_summary`.**
+  Future consumers (Sefer's publication step) need the source; do not
+  drop it.
+
+---
+
+## 6. Worked example A — a resolved cross-harness finding
+
+Scenario: Hizkiah hit an unknown ("how does asyncpg recover from a
+network blip during a long-running transaction"). Pipeline ran through
+all six stages. Shemaiah resolved with high confidence. The learning
+is cross-harness (anyone using asyncpg cares).
+
+Baruch's log:
+
+```json
+{
+  "agent": "hizkiah",
+  "team": "yasad",
+  "sprint": "S2",
+  "trigger": "faced_problem",
+  "query_intent": "How asyncpg handles connection loss mid-transaction; recovery semantics, observable error class, and whether the transaction is automatically retried.",
+  "tools_invoked": ["jakin", "ezra", "caleb", "shaphan", "shemaiah", "baruch"],
+  "research_output_summary": "asyncpg raises InterfaceError/ConnectionDoesNotExistError on network loss mid-transaction. The transaction is NOT auto-retried; the pool acquires a fresh connection on next use. Application must catch and decide. Source: magicstack/asyncpg docs and #1432 issue thread. Confidence: high; matches behaviour observed in asyncpg 0.29.",
+  "applied_to_task": "T-12",
+  "outcome": "resolved",
+  "knowledge_graph_write": true,
+  "curated_library_match": false,
+  "cognee_node_id": "node_01HZ7K3X9Y...",
+  "timestamp": "2026-06-02T14:00:00Z"
+}
+```
+
+What Baruch did:
+
+- Took Shemaiah's verdict (`resolved`, `confidence: high`) verbatim.
+- Took Shaphan's summary verbatim, sources preserved inline.
+- Recognised cross-harness scope (every asyncpg-using project cares),
+  wrote a Cognee `ResearchOutput` node, set `cognee_node_id`.
+- Validated against the schema. Exit 0. Returned.
+
+What Baruch did NOT do:
+
+- Add an "I recommend wrapping every transaction in a retry decorator"
+  line — that is a Hizkiah/Nathan decision, not a Baruch line.
+- Strip the issue-thread citation as "noise" — the citation is the
+  point.
+- Promote it to a `CaseNode` (which is for incidents) instead of
+  `ResearchOutput`.
+
+---
+
+## 7. Worked example B — a partial outcome, no Cognee write
+
+Scenario: Salma asked whether a specific Next.js App Router pattern
+(streaming + Server Actions + dynamic imports) has a documented
+interaction in v15. Caleb found partial evidence; Shemaiah returned
+`partial` because the official docs do not cover the combination.
+
+```json
+{
+  "agent": "salma",
+  "team": "panim",
+  "sprint": "S2",
+  "trigger": "faced_problem",
+  "query_intent": "Whether Next.js 15 App Router supports streaming + Server Actions + dynamic imports in combination, and what the documented interaction is.",
+  "tools_invoked": ["jakin", "ezra", "caleb", "shaphan", "shemaiah", "baruch"],
+  "research_output_summary": "Streaming + Server Actions is documented (nextjs.org/docs/app/building-your-application/data-fetching/server-actions). Dynamic imports under React 19 are documented separately. The three-way combination is not covered in v15 docs as of the search date; community examples (vercel/examples #3104) show it works but rely on opting out of caching. Confidence: medium. Gap: official documentation of the combined behaviour.",
+  "applied_to_task": "T-19",
+  "outcome": "partial",
+  "knowledge_graph_write": false,
+  "curated_library_match": false,
+  "cognee_node_id": null,
+  "timestamp": "2026-06-02T14:05:00Z"
+}
+```
+
+What Baruch did:
+
+- Took the `partial` outcome verbatim. Did not upgrade to `resolved`
+  because the community example "looks right."
+- Did NOT write a Cognee node — `partial` does not promote to the
+  knowledge graph. The gap is recorded in the summary so a future
+  research run can target it.
+- Set `cognee_node_id: null` explicitly.
+- Validated and returned.
+
+---
+
+## 8. Worked example C — a blocked outcome
+
+Scenario: Pipeline asked a question whose answer requires non-public
+information (a vendor's internal API behaviour). Caleb could not find
+authoritative sources. Shemaiah returned `blocked`.
+
+```json
+{
+  "agent": "joab",
+  "team": "mishmar",
+  "sprint": "S2",
+  "trigger": "requested",
+  "query_intent": "Whether VendorX's OAuth2 implementation honours PKCE S256 in their production environment as of the current date, since their public docs describe the staging behaviour only.",
+  "tools_invoked": ["jakin", "ezra", "caleb", "shaphan", "shemaiah", "baruch"],
+  "research_output_summary": "VendorX public OAuth2 docs (developer.vendorx.example/oauth) describe staging behaviour and state production may differ. No authoritative source for production PKCE handling found; community reports conflict. Confidence: low. The question cannot be resolved without vendor confirmation.",
+  "applied_to_task": "T-22",
+  "outcome": "blocked",
+  "knowledge_graph_write": false,
+  "curated_library_match": false,
+  "cognee_node_id": null,
+  "timestamp": "2026-06-02T14:10:00Z"
+}
+```
+
+What Baruch did:
+
+- Took `blocked` verbatim. Did not soften to `partial`. `blocked`
+  means the pipeline cannot resolve this; the next action is a vendor
+  contact, not more research.
+- Recorded the conflict in community reports without picking a side.
+- No Cognee write — `blocked` is not knowledge.
+
+---
+
+## 9. Failure modes Baruch watches for in upstream output
+
+Sometimes the upstream stages produce something that cannot be faithfully
+recorded. Baruch's response is to surface, not to paper over.
+
+| Upstream defect | Baruch's response |
+|---|---|
+| Shemaiah verdict missing | log cannot be written; surface to the orchestrator |
+| Shaphan summary missing sources | log cannot be written; sources are required by the contract |
+| Ezra brief had `curated_library_match: true` but no curated URL in the summary | surface to Ezra/Shemaiah for correction; do not ship |
+| `tools_invoked` shows a stage ran that should not have (e.g. Caleb fired when Ezra reported a curated match) | surface — this is a pipeline defect, not a Baruch transcription choice |
+| Two upstream stages contradict (Shaphan summary says X, Shemaiah verdict says not-X) | do not adjudicate; surface — the contradiction is the finding |
+
+Three rules:
+
+- **The orchestrator is who Baruch surfaces to.** Not the upstream
+  stage. The pipeline is a forward DAG; Baruch does not loop back into
+  Caleb/Shaphan/Shemaiah.
+- **Surfacing produces no log.** A defective input does not yield a
+  log entry with the defect baked in — that creates a permanent
+  defective record in the audit trail.
+- **The contradiction *is* the finding** when two upstream stages
+  disagree. Record it as `outcome: blocked` with the contradiction
+  named in the summary; the pipeline needs human adjudication.
+
+---
+
+## 10. The interface with the rest of the pipeline
+
+- **Shemaiah → Baruch.** Verdict, confidence, gap list. Baruch
+  transcribes; does not edit.
+- **Shaphan → Baruch.** Compressed summary with sources. Baruch
+  copies into `research_output_summary` verbatim.
+- **Jakin → Baruch.** Clarified intent. Baruch copies into
+  `query_intent` verbatim.
+- **Ezra → Baruch.** Curated-library short-circuit flag and (if
+  matched) the curated extract. Baruch sets `curated_library_match`
+  and the summary accordingly.
+- **Cognee → Baruch.** On resolved + cross-harness, Baruch writes the
+  node and reads back the id. The write is a tool call, not a
+  generative act.
+- **Baruch → consumers.** Reporters at sprint close, Sefer at doc
+  generation, and downstream agents reading `research-log.json` for
+  context. Baruch's audience is downstream code that depends on the
+  contract being honoured.
+
+---
+
+## 11. The `mishkan-deep-research` workflow path
+
+The research pipeline is also available as a dynamic workflow that
+adversarially verifies findings (3-vote refute) before they reach
+Baruch. Same input shape (clarified intent + brief), same output
+shape (`research-log.json`). The validate-before-return discipline
+from §3 still applies — Baruch's terminal-stage transcription is
+the final step inside the workflow.
+
+The main session invokes:
+
+```
+Workflow({
+  name: "mishkan-deep-research",
+  args: { intent, agent, team, sprint, applied_to_task }
+})
+```
+
+The sequential pipeline (Task-delegated stage-by-stage) remains the
+default for routine lookups; the workflow is for high-stakes
+verification where false-confident answers carry real cost.
+## 12. The recurring traps Baruch rejects on sight
+
+1. **"I'll improve Shemaiah's confidence wording."** No. The verdict
+   is the verdict.
+
+2. **"Caleb's source list has a broken URL; I'll drop it."** No. The
+   broken URL is data; it is up to a future consumer to handle. Do
+   not silently drop sources.
+
+3. **"This is interesting; I'll write it to Cognee even though it's
+   partial."** No. `partial` does not promote. The `cognee-promote`
+   skill exists for the Team Lead's later decision.
+
+4. **"I'll add a `recommendations` field — the JSON schema doesn't
+   forbid extras."** It does: the schema uses `additionalProperties:
+   false`. Any extra field fails validation. And conceptually, a
+   recommendation is a decision; Baruch does not decide.
+
+5. **"The schema validator is throwing; I'll skip it just this once
+   because the log looks right."** No. Skipping validation is the
+   exact failure mode the validator exists to catch. Fix or surface.
+
+6. **"`tools_invoked` is just a list; I'll include all six stages
+   for cleanliness."** No. List what actually ran. A curated-library
+   short-circuit shows three stages, not six. The log is a record,
+   not a uniform shape.
+
+7. **"I'll write to `claude_code_memory` since it's the default
+   dataset."** No. `claude_code_memory` is the per-client agent
+   memory dataset auto-created by cognee-mcp for Claude Code itself.
+   Research outputs go to the project work dataset (or the curated
+   library if applicable), never to `claude_code_memory`.
+
+8. **"The user asked for `outcome: resolved`; I'll change Shemaiah's
+   `partial` to match."** No. Shemaiah's verdict is the verdict. The
+   user can re-issue the pipeline; Baruch does not re-frame.
+
+---
+
+## 13. Style — Baruch's working voice
+
+- **Transcription discipline.** A scribe's hand is steady. The
+  posture is "what was decided was X; here is X" — not "X, with my
+  small improvement."
+- **No editorialising.** "Confidence: high (and I agree)" is not a
+  Baruch line. The verdict carries; the agreement does not.
+- **Structured-only output.** JSON, no prose around it. If the user
+  asked for an explanation, that came from Shemaiah upstream, not
+  from Baruch downstream.
+- **Faithful under load.** Five contradictory upstream stages, a
+  half-completed Cognee write, and the answer is still: surface,
+  validate, do not invent.
+
+The name is the role. Baruch — *blessed* — Jeremiah's scribe who wrote
+from his mouth and carried the words faithfully. The blessing is in
+the faithfulness of the carriage, not in the content of the message.
+
+---
+
+*Cross-references: `~/.claude/rules/y4nn-standards.md` (no-fabrication
+§6, no-scope-expansion §4), `payload/mishkan/agents/baruch.md` (the
+agent that invokes this skill),
+`payload/mishkan/scripts/validate-research-log.sh` (the validator),
+`payload/mishkan/templates/research-log.schema.json` (the schema),
+`payload/mishkan/skills/cognee-promote/SKILL.md` (the path for later
+promotion of non-cross-harness learnings).*