Skip to content
This repository was archived by the owner on Oct 26, 2026. It is now read-only.

Document company_onboarding brief purpose in Context reference - #365

Draft
sidneyswift wants to merge 2 commits into
mainfrom
claude/ctx-2134-release-runbook
Draft

sidneyswift wants to merge 2 commits into
mainfrom
claude/ctx-2134-release-runbook

Conversation

@sidneyswift

@sidneyswift sidneyswift commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Superseded by recoupable/docs#360 — marked draft; do not merge both. docs#360 (ticket #2130, "Document company_onboarding briefs and evidence freshness") makes the same purpose enum change in the same hunks, adds a purpose description, the assessment_scope/next_steps response text and a company_onboarding example, and is the more complete PR. recoupable/docs#358 (draft, ticket #2118) also adds the enum value. The three conflict with each other (git merge-tree), so only one can land unchanged. Recommendation: merge docs#360 and close this PR unmerged. Kept open as a draft only so a reviewer can compare the wording; the one caveat this PR states that docs#360 does not ("missing topics are review prompts, not proof that evidence does not exist") can be carried over there if wanted.

Summary

Brings the public Context reference in line with shipped behavior for the company_onboarding brief purpose, which merged and went live via database#96 → api#992 → app#2178 but is still missing from api-reference/openapi/context.json on docs main. Adds company_onboarding to the purpose enum of the brief and save_brief request branches, documents what that purpose adds to the response (assessment_scope: "selected_saved_context_requests" and per-request next_steps with review_assessment_coverage / review_available_evidence), states that missing topics are coverage prompts rather than proof evidence does not exist and that submitted names/metadata do not establish rights or ownership, and notes that only saving (save_brief) needs migration 20261010010000_context_company_assessment.sql; the read-only brief action compiles the purpose in api code. This advances #2134's Done-when item "Public docs and MCP match shipped behavior". The MCP input schema is shared with the API Zod schema, but the human-readable MCP tool descriptions (context, compile_music_context_brief, save_music_context_brief) also still name only creative direction and playlist pitch, so the docs are not the only surface that lags (documented in the api runbook, recoupable/api#1012, section 2.2). Additive, anchored JSON edits only: no path, example or existing enum value removed; no new MDX page; no docs.json change.

Refs recoupable/app#2134 (child of epic recoupable/app#2116).

Merge sequencing

docs → database → api → app. Superseded by recoupable/docs#360 (see the note above). No code dependency: the behavior described is already merged and released (database#96, api#992, app#2178). Sibling PR for this ticket: recoupable/api#1012 (release runbook + guard test), which does not depend on this PR and references docs#360 as the preferred docs change. No database or app PR for this ticket.

Verification

  • Ran: python3 -c "import json;json.load(open('api-reference/openapi/context.json'))" — parses.
  • Ran: assertion script — brief and save_brief purpose enums both contain company_onboarding; the brief purpose description no longer claims the migration is required; the save_brief purpose description does; the 200 response description contains assessment_scope — ok.
  • Ran: additive check against origin/main — all previous paths and every previous enum value retained (10 insertions, 6 deletions; the deletions are the replaced description strings and the two enum closers, each replaced by a superset).
  • Ran: git merge-tree against the docs#358 and docs#360 branches — both conflict with this PR (same hunks).
  • Red → green: not applicable (documentation-only change; the matching api guard test lives in Add Context release runbook with guard test api#1012).
  • Not verified: hosted deployment (docs.recoupable.dev render of the updated enum/description), live providers, production database. No deployment, migration or provider call was performed.

Out of scope / known gaps

  • The remaining shared actions (plan, read_execution, release-case and release-track actions, name/brief/text intake) are still documented only in api/lib/context/README.md and the MCP tool schema.
  • MCP tool description lag (see Summary) is not fixed here.
  • Cost reconciliation (#2123/#2105), Sites quality (#2094/#2133), the live pilot and broad release remain gated and untouched.

🤖 Generated with Claude Code

The company_onboarding purpose shipped through database#96, api#992 and
app#2178 but the public OpenAPI reference still listed only
creative_direction and playlist_pitch, so public docs no longer matched
shipped HTTP/MCP behavior. Add the enum value on the brief and
save_brief branches, describe assessment_scope and per-request
next_steps, state the coverage-not-proof and no-rights caveats, and name
the required company-assessment migration. Additive edits only.

Refs recoupable/app#2134

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Oct 10, 2026 •

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 84517a80-da4d-4b1a-b425-a49df01f16c4

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api-reference/openapi/context.json">

<violation number="1" location="api-reference/openapi/context.json:301">
P3: The 200 response description names the `next_steps` entry fields as "requestId, action (review_assessment_coverage or review_available_evidence) and that request's missing topics", but the operation description names the third field `topics`. A consumer reading only the response section cannot tell the field is called `topics`. Name it explicitly, e.g. "requestId, action, and topics (that request's missing topics)", so both sections agree on the field name.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic

},
"200": {
"description": "Read returns request. Brief returns request_id, request_ids, purpose, readiness, bounded Markdown text and text_characters, documents and their serialized characters count, missingTopics, guidance, gaps, request_coverage, and input_manifest. Each coverage entry includes requestId, readiness and missingTopics; overall readiness remains partial if any request has a gap or partial evidence. The manifest includes compilerVersion, method, requestIds, excludedTopics, and selected documents with documentId, resultId (null only if unavailable), subjectId, topic, version and sourceVersionIds. The result is returned without creating a saved brief record. Save/read brief return {snapshot: {id, created_at, purpose, state, superseded, brief}}. state is saved or unavailable; unavailable snapshots return brief: null. saved snapshots return the exact compiled response including its input manifest. Another workspace cannot read the record."
"description": "Read returns request. Brief returns request_id, request_ids, purpose, readiness, bounded Markdown text and text_characters, documents and their serialized characters count, missingTopics, guidance, gaps, request_coverage, and input_manifest. Each coverage entry includes requestId, readiness and missingTopics; overall readiness remains partial if any request has a gap or partial evidence. The manifest includes compilerVersion, method, requestIds, excludedTopics, and selected documents with documentId, resultId (null only if unavailable), subjectId, topic, version and sourceVersionIds. The result is returned without creating a saved brief record. Save/read brief return {snapshot: {id, created_at, purpose, state, superseded, brief}}. state is saved or unavailable; unavailable snapshots return brief: null. saved snapshots return the exact compiled response including its input manifest. Another workspace cannot read the record. For purpose company_onboarding, brief and save_brief responses (and read_brief snapshots of them) additionally include assessment_scope (always selected_saved_context_requests) and next_steps: one entry per request with requestId, action (review_assessment_coverage or review_available_evidence) and that request's missing topics."

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The 200 response description names the next_steps entry fields as "requestId, action (review_assessment_coverage or review_available_evidence) and that request's missing topics", but the operation description names the third field topics. A consumer reading only the response section cannot tell the field is called topics. Name it explicitly, e.g. "requestId, action, and topics (that request's missing topics)", so both sections agree on the field name.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At api-reference/openapi/context.json, line 301:

<comment>The 200 response description names the `next_steps` entry fields as "requestId, action (review_assessment_coverage or review_available_evidence) and that request's missing topics", but the operation description names the third field `topics`. A consumer reading only the response section cannot tell the field is called `topics`. Name it explicitly, e.g. "requestId, action, and topics (that request's missing topics)", so both sections agree on the field name.</comment>

<file context>
@@ -294,7 +298,7 @@
           },
           "200": {
-            "description": "Read returns request. Brief returns request_id, request_ids, purpose, readiness, bounded Markdown text and text_characters, documents and their serialized characters count, missingTopics, guidance, gaps, request_coverage, and input_manifest. Each coverage entry includes requestId, readiness and missingTopics; overall readiness remains partial if any request has a gap or partial evidence. The manifest includes compilerVersion, method, requestIds, excludedTopics, and selected documents with documentId, resultId (null only if unavailable), subjectId, topic, version and sourceVersionIds. The result is returned without creating a saved brief record. Save/read brief return {snapshot: {id, created_at, purpose, state, superseded, brief}}. state is saved or unavailable; unavailable snapshots return brief: null. saved snapshots return the exact compiled response including its input manifest. Another workspace cannot read the record."
+            "description": "Read returns request. Brief returns request_id, request_ids, purpose, readiness, bounded Markdown text and text_characters, documents and their serialized characters count, missingTopics, guidance, gaps, request_coverage, and input_manifest. Each coverage entry includes requestId, readiness and missingTopics; overall readiness remains partial if any request has a gap or partial evidence. The manifest includes compilerVersion, method, requestIds, excludedTopics, and selected documents with documentId, resultId (null only if unavailable), subjectId, topic, version and sourceVersionIds. The result is returned without creating a saved brief record. Save/read brief return {snapshot: {id, created_at, purpose, state, superseded, brief}}. state is saved or unavailable; unavailable snapshots return brief: null. saved snapshots return the exact compiled response including its input manifest. Another workspace cannot read the record. For purpose company_onboarding, brief and save_brief responses (and read_brief snapshots of them) additionally include assessment_scope (always selected_saved_context_requests) and next_steps: one entry per request with requestId, action (review_assessment_coverage or review_available_evidence) and that request's missing topics."
           },
           "400": {
</file context>

The read-only brief action compiles company_onboarding in api code and
never calls save_context_brief, so only save_brief (and snapshots read
back with read_brief) depends on 20261010010000_context_company_assessment.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant