Open Questions & Pending Decisions

All unresolved design decisions, ambiguities, and areas where the spec is incomplete. Each item is assigned a unique ID so it can be referenced from other docs and tracked.

Items marked 🔴 Blocking must be resolved before the indicated phase begins. Items marked 🟡 Pre-launch must be resolved before production. Items marked 🟢 Post-MVP can wait.

Architecture & Infrastructure

OQ-1 — Worker process lifecycle

Priority: 🔴 Blocking Phase 1

Should BullMQ workers be pre-created for all agent roles at API startup, or created lazily when a tenant’s first task is enqueued?

OQ-2 — Cross-tenant BullMQ queue monitoring

Priority: 🟡 Pre-launch

Queues are shared per agent role: agent__{agentRole}. All tenants share the same queue; Bull Board/Arena shows one queue per agent role, which aggregates nicely. Jobs carry tenantId in the payload for filtering.

Options:

• Build a custom Manage App view that queries Redis key patterns directly
• Use BullMQ Pro’s native group/namespace support
• Custom aggregation layer in the API

OQ-3 — ClaudeAdapter callback pattern

Priority: 🔴 Blocking Phase 1

The ClaudeAdapter runs Claude as a local child process (synchronous). The WebhookAdapter needs a callback URL for async results. Should the adapter interface require a callback URL from all adapters, or only from async ones?

Current thinking: Synchronous adapters (Claude, Ollama) return results directly and do not emit a callback URL. The interface is unified — sync adapters resolve immediately; the webhook adapter defers. Needs confirmation before the adapter interface is finalised.

OQ-4 — Activity template schema and versioning

Priority: 🔴 Blocking Phase 2

The activity_templates table is referenced in the DB schema but the steps JSON structure is not yet defined. Also undefined:

• Can tenants customise a global template, or are templates global-only?
• How are template versions managed when a global template is updated after tenants have copied it?

OQ-5 — Goal progress update frequency

Priority: 🟡 Pre-launch

Currently designed as monthly (Data Analyst updates goals.current_value in the monthly report). Options:

• Monthly only (simple, matches billing cycle)
• Mid-month lightweight check (more responsive, slightly higher cost)
• On-demand (tenant can trigger a goal check at any time)

OQ-6 — Partial deliverable period completion

Priority: 🟡 Pre-launch

If a deliverable period ends with fewer completions than target (e.g. 7/10 blog posts), what happens?

• Mark as partial_complete and carry the shortfall to the next period
• Each period is standalone — no carryover
• DM Portal alert for manual decision to extend or accept partial

OQ-7 — Strategy refresh mid-period

Priority: 🟡 Pre-launch

If a tenant requests a strategy refresh mid-month, how are in-progress activities in the current deliverable period resolved? Options:

• Complete them under the old deliverable, then migrate to new strategy
• Cancel in-progress activities and start fresh under new strategy
• Migrate them if activity type matches; cancel if not

Agent-Specific

OQ-8 — Onboarding Agent without SEMrush/Ahrefs

Priority: 🟡 Pre-launch

The Onboarding Agent uses SEMrush and Ahrefs for keyword and competitor data. On Free plan (no integrations), the agent must still produce a usable context file. Which sections are skipped vs. left as “Not identified”? The agent’s prompt and output template need explicit fallback instructions for each missing data source.

OQ-9 — Content Researcher on cloud deployments

Priority: 🟡 Pre-launch

Content Researcher is specified as Ollama-only. In a SaaS (cloud) deployment where the tenant has not provisioned a local Ollama instance, three options:

• Disable Content Researcher unless Ollama is configured (Agency/Enterprise only)
• Fall back to Claude Haiku for non-competitor tasks only
• Content Researcher is always Agency/Enterprise plan only

The plan availability table in agents/content-researcher.md needs updating once decided.

OQ-10 — Activity Planner orchestration model

Priority: 🟡 Pre-launch

Does the Activity Planner create the full activity pipeline upfront at the start of a deliverable period, or does it run reactively — deciding the next step after each human approval gate?

SaaS & Billing

OQ-11 — Free plan limits (fully defined)

Priority: 🔴 Blocking Phase 2

The Free plan is mentioned but not fully specified. Needs:

• Maximum concurrent tenants on Free (or unlimited with feature gates only)
• Monthly LLM cost cap per free tenant (the platform absorbs this cost)
• Whether a payment method is required on file for Free accounts

OQ-12 — Overage billing on Pro plan

Priority: 🟡 Pre-launch

When a Pro tenant exceeds their monthly LLM cost cap:

• Hard stop: agents pause; tenant must upgrade to resume
• Soft cap: overage charged at a metered rate via Razorpay usage billing
• Notify only: alert sent, no automatic action (simplest for MVP)

UI & UX

OQ-13 — DM Portal reviewer assignment model

Priority: 🟡 Pre-launch

A DM reviewer in the DM Portal sees pending activities across multiple tenants. How are items assigned?

• Claimed: First reviewer to act on it takes ownership
• Assigned: Platform admin explicitly assigns a reviewer to each tenant
• Open: Any reviewer can action any item across all tenants

This affects the Activities Inbox (W6) design and the reviewer_id field on activities.

OQ-14 — Dashboard role permissions (member vs. admin)

Priority: 🟡 Pre-launch

Within the Dashboard app, the following are undefined:

• Can member role approve activities, or is approval restricted to admin?
• Can member role edit the client context file?
• Are billing and cost screens visible to all roles, or admin-only?

OQ-15 — Org chart live agent status

Priority: 🟢 Post-MVP

The Org Chart (screen D9) includes agent nodes. Should these show real-time status (idle / running / error)? Requires SSE or polling of active activity_runs. Deferred to Phase 4 pending complexity assessment.

Channels & Publishing

OQ-16 — Phone-home JWT signing key rotation

Priority: 🟡 Pre-launch

Task-scoped JWTs validate agent callbacks. Process for key rotation is not designed — specifically, what happens to in-flight callbacks when the key rotates.

OQ-17 — Uploaded document security scanning

Priority: 🟡 Pre-launch

Tenants upload PDFs and DOCX files during onboarding and via Knowledge Base. Current protection is file type validation + size limit only. Should ClamAV (or equivalent) scan uploads before text extraction?

OQ-18 — OAuth token encryption key rotation

Priority: 🟡 Pre-launch

Channel OAuth tokens are encrypted with AES-256-GCM. The key is stored in Doppler. Key rotation requires re-encrypting all stored tokens. The rotation process and rollback procedure are not yet designed.

OQ-19 — OAuth app ownership (LinkedIn, Meta, Google)

Priority: 🔴 Blocking Phase 2

For OAuth channel connections (LinkedIn, Meta, Google), does the platform run a single OAuth app that all tenants authenticate through, or does each tenant create their own OAuth app?

Current assumption: Platform-owned OAuth app (standard for SaaS agency platforms). Tenants authorise the platform’s app to access their accounts. Risk: LinkedIn and Meta Marketing API access requires official partner/developer status.

OQ-20 — Social post scheduled publishing

Priority: 🟡 Pre-launch

When a SocialPost has a scheduled_for time, who executes the publish:

• BullMQ delayed job (agent-created, runs at the scheduled time)
• Human manually triggers publishing via the Dashboard at the scheduled time
• Third-party scheduler (Buffer, Later) — platform creates the post there instead

OQ-21 — Blog request creation in automated pipeline

Priority: 🟡 Pre-launch

In the blog deliverable pipeline, the SEO Specialist researches topics and outputs a list. Does this output automatically create BlogRequest records (with requested_by_type = 'agent'), or does a human manually create them after reviewing the list?

Current design: SEO Specialist creates BlogRequest records directly; the subsequent approval activity is the blog request review. Needs explicit confirmation before Phase 2.

OQ-22 — Lead enrichment provider

Priority: 🟢 Post-MVP

For auto-enriching leads (LinkedIn profile, company size, industry), no tool is specified. Options: Clearbit, Apollo, Hunter.io, or LinkedIn API (rate-limited). Not in the integration list.

OQ-23 — Channel score recalculation frequency

Priority: 🟢 Post-MVP

Current design: monthly (same as Data Analyst report). Weekly would be more actionable. On-demand (on each new publish) would be most responsive but expensive. Decision deferred until channel scoring is implemented.

OQ-24 — Facebook Lead Ads webhook integration

Priority: 🟡 Pre-launch

For capturing Facebook Lead Ads leads:

• Meta Webhooks (subscribe to leadgen events) — requires a verified webhook endpoint
• Polling — simpler but not real-time
• Zapier/Make intermediary — no direct integration, tenant sets up the zap

Recommended: Meta Webhooks. Requires the platform to pass Meta’s webhook verification review.

RAG / Knowledge Base

OQ-25 — Context window token budget (skills + RAG combined)

Priority: 🟡 Pre-launch

Two-stage skill loading (see skills-system.md) reduces the skills footprint to manifest tokens + only the skills the agent elects to load. This eliminates the worst case (all skills + all RAG chunks). However, a formal token budget for the remaining components — loaded skills, RAG chunks, task content, and conversation history — still needs to be defined and enforced.

Remaining decision: what happens when the agent has loaded several skills and a high topK RAG result set that together approach the context limit?

• Hard cap on RAG topK when skills are loaded (e.g. topK ≤ 10 if > 2 skills loaded)
• Soft warning logged; agent continues (risks truncation)
• Hard error: task fails, operator notified to reduce skill assignments or lower topK default

OQ-26 — Chunking strategy for structured documents

Priority: 🟡 Pre-launch

PDFs with tables (pricing sheets, spec documents) lose their table structure when chunked as raw text. Options:

• Table-aware chunker that converts tables to Markdown before chunking
• Use Docling parser (which preserves table structure) as the default for PDFs with tables
• Accept loss of structure for MVP; address in a later iteration

OQ-27 — Re-indexing flow when a document is updated

Priority: 🟡 Pre-launch

If a tenant replaces a document (e.g. uploads a new version of their brand guidelines), the old chunks remain in Qdrant. A “delete + re-index” flow must be defined:

• Delete all Qdrant points where fileId matches the old file
• Ingest the new file

The UI needs to support a “replace file” action distinct from “delete then upload”, so the re-index is triggered atomically.

OQ-28 — Crawl scope for large websites

Priority: 🟡 Pre-launch

Tenants with large e-commerce sites (1,000+ pages) would exceed the default crawl limit of 200 pages and may only want specific sections indexed (e.g. only /blog/* and /services/*). The crawl settings UI (KB6) includes a URL path filter field but the backend enforcement and the per-plan page limits are not yet decided.

See plan limits table in rag-integration.md.

OQ-29 — RAG cost attribution (embedding API calls)

Priority: 🟡 Pre-launch

Embedding API calls have a cost (OpenAI charges per token). These are currently outside the llm_calls audit trail. Options:

• Add embedding calls to the existing llm_calls table with a callType: 'embedding' field
• Create a separate embedding_calls table
• Include embedding costs in the per-tenant monthly cost report without per-call logging

OQ-30 — Reranker availability when Ollama is not configured

Priority: 🟡 Pre-launch

The reranker model (bge-reranker-v2-m3) runs via Ollama. On SaaS cloud deployments without a local Ollama instance, reranking would be unavailable. Options:

• Disable reranking unless Ollama is available (silently degrade to RRF-only)
• Use a cloud reranker API (Cohere Rerank, etc.) as a fallback
• Make reranking an Agency/Enterprise-only feature (requires on-prem or Ollama configured)

OQ-31 — RAG for Free plan tenants

Priority: 🟡 Pre-launch

The plan availability table in rag-integration.md shows Free tenants get limited RAG (5 files, 50 crawl pages). This needs product confirmation — Free tenants using RAG incurs Qdrant storage and embedding API costs for the platform.

Skills System

OQ-32 — Skills versioning in activity runs

Priority: 🟢 Post-MVP

Should the exact skill versions used in each activity_run be snapshotted so that a run can be replayed with identical context? This would require storing skillIds[] on activity_runs. Adds implementation complexity; the main benefit is debugging reproducibility.

OQ-33 — Skill file size limit

Priority: 🟡 Pre-launch

Two-stage loading means individual skill files are loaded on demand rather than all at once, reducing the blast radius of an oversized skill. However, a per-skill size limit is still needed because a single very large skill loaded mid-run could still exhaust the agent’s remaining context budget.

A max-tokens guard must be enforced in the load_skill tool handler. The guard should fail with a clear error (returned to the agent as a tool error, not a silent truncation) so the agent can proceed without the skill or surface the issue to the operator.

Dashboard UX — Observed in Live App (Mar 31, 2026)

OQ-34 — “Vault” vs “Business Info” naming

Priority: 🟡 Pre-launch

The sidebar nav label is “Business Info” but the page heading is “Vault”. These should be consistent. Decision needed: is the product name for this section “Vault” or “Business Info”?

OQ-35 — Users screen — invite/manage functionality

Priority: 🟡 Pre-launch

The live /settings/users screen shows only a read-only table with a detail slide-over. No “Invite User” button or role-edit functionality was observed. Is user management handled elsewhere (e.g., admin portal), or is it planned but not yet built for the client-facing dashboard?

OQ-36 — Chat screen — AI response failures in history

Priority: 🟡 Pre-launch

When viewing a past conversation in the chat history, AI responses were missing or empty (only user messages visible as purple bubbles). Needs investigation: are AI responses not being stored, or is there a rendering issue when loading historical messages?

OQ-37 — Activities list — no “Add Activity” button

Priority: 🟡 Pre-launch

The /activities screen shows 937 pages of activities but no button to create a new activity from the client dashboard. Is activity creation agency-side only (via DM Portal), or is it planned for the client dashboard?

OQ-38 — Report detail — no download/export button

Priority: 🟡 Pre-launch

The report detail page (/reports/detail/[id]) renders a rich HTML report but no “Download as PDF” button was observed. The Strategy page has a “Download as PDF” button. Is this an intentional omission for reports, or a missing feature?

Dashboard Screens — Specification Gaps

OQ-39 — Strategy screen mobile behaviour

Priority: 🟡 Pre-launch

The Strategy screen renders its content inside an iframe. Mobile availability is undefined. The iframe embed may not render acceptably on small screens — a decision is needed: serve a simplified mobile layout, redirect to PDF download, or mark as web-only.

OQ-40 — Goals and Deliverables mobile availability

Priority: 🟡 Pre-launch

Mobile availability for Goals (/goals) and Deliverables (/deliverables) is undefined. Both screens have been marked TBD.

OQ-41 — Activities and Deliverables alternative view modes

Priority: 🟡 Pre-launch

The Activities screen exposes three additional view modes beyond the default list: stack/group, and calendar. The Deliverables screen has a month picker but only one view mode. The layout and behaviour of the stack/group and calendar views for Activities have not been specified.

OQ-42 — Empty states for Strategy and Goals

Priority: 🟡 Pre-launch

No empty state is defined for the Strategy screen (when no strategy document exists) or the Goals screen (when no goals are configured for the tenant). Should a placeholder, call-to-action, or instructional message be shown?

OQ-43 — Reports list sort order and PDF download placement

Priority: 🟡 Pre-launch

Two related gaps:

1. The Reports list sort order (newest-first vs oldest-first) is undefined.
2. PDF download is available on the Strategy detail page but absent from Report Detail. Should it be on the list row, the detail page, or both?

OQ-44 — Users screen: invite and role management for Owner role

Priority: 🟡 Pre-launch

The Users screen (/settings/users) is currently view-only for client users (slide-over shows read-only fields). It is unclear whether users with the Owner role should be able to invite new users, edit roles, or remove users — and if so, on which screen.

OQ-45 — Contract document upload on Vault screen

Priority: 🟡 Pre-launch

The Business Info / Vault Overview tab shows a “Contract Documents” section that displays “No contract documents found” but provides no upload button. Clarification needed: is contract upload an admin-only operation (managed from the DM/Agency portal), or should clients be able to upload documents themselves?

OQ-46 — Channel Health Score implementation status

Priority: 🟡 Pre-launch

The Channel Health Score feature (overall score 0–100, sub-scores for Profile Completeness / Posting Activity / Engagement Rate / Follower Growth / Content Variety, improvement suggestions) was in the original spec but is not present in the live Channels screen. Confirm whether this is planned, deferred, or cancelled.

OQ-47 — Agent Chat history sidebar default state

Priority: 🟢 Post-MVP

Whether the Agent Chat history sidebar defaults to open or collapsed on initial page load is undefined. Should it remember the user’s last toggle state (localStorage) or always start in a fixed state?

Screen ID Naming

OQ-49 — Lead Nurture Agent (post-MVP consideration)

Priority: 🟢 Post-MVP

The Leads screen (D15) is currently read-only — view and status changes only. A Lead Nurture Agent could score incoming leads, suggest follow-up actions, and draft outreach copy. Deferred because lead CRM functionality is not fully specced. Decide: should Leads grow into a lightweight CRM within Leadmetrics, or remain a data-display screen fed from connected channels?

OQ-50 — Social Community Manager Agent (post-MVP consideration)

Priority: 🟢 Post-MVP

Responding to social media comments and DMs is a standard DM agency service not covered by any current agent. Requires real-time webhook monitoring per connected platform and careful guardrails to avoid brand-damaging responses. Complexity and moderation risk make this Enterprise-tier post-launch. Should this be a separate agent or a mode of the Social Media Manager?

Screen ID Naming

OQ-48 — Dashboard planned screens conflict with DM Portal screen IDs

Priority: 🟡 Pre-launch

screens-dashboard.md Part 2 uses screen IDs P1–P16 for planned agent-layer screens. The DM Portal uses P1–P8 for its own screens. These prefixes collide.

Options:

• Rename Dashboard planned screens to D14–D29 (continuing the D-series)
• Keep P prefix but scope it: DP1–DP16 for Dashboard planned, R1–R8 for DM Portal reviewer
• Keep current IDs but accept ambiguity and resolve by context (app name)

Recommended: rename Dashboard planned screens to D14–D29 to keep the Dashboard series consistent and avoid cross-app ID conflicts.