Interface and delivery

Research Question

Once research is complete and outputs are produced, how should they be surfaced and delivered to the people (or agents) who need them? What interfaces make research outputs most usable?

Findings

Executive Summary

The research corpus requires two parallel delivery channels, one per consumer type: the GitHub wiki (already live) serves the human researcher via the repository's Wiki tab on web and iOS, and an MCP server with stdio transport (designed, not yet implemented) serves AI agents via search_research, get_research_item, and get_related_items tools. The CLI research search command is designed and shares the same FTS5 backend; it is the third channel to implement. Email digest and Slack push notification are architecturally viable but blocked under current constraints: both require credentials (RESEND_API_KEY/EMAIL_RECIPIENT for email; SLACK_WEBHOOK_URL for Slack) that are not in the approved credentials table and require owner approval before implementation can proceed.

Key Findings

1. The GitHub wiki is the correct and already-live human-browsing interface: publish-wiki.yml rebuilds all pages from Research/completed/ on every push to main, producing a date-sorted Home.md and tag-indexed _Sidebar.md accessible from the repository's Wiki tab on both the GitHub website and the iOS app. [High confidence]

2. An MCP server with stdio transport, registered in .github/mcp.json, is the only agent-query interface that satisfies all repository constraints: no persistent server process, no new credentials, compatible with the 10 existing MCP stdio servers. [High confidence]

3. The three-tool MCP interface contract defined in 2026-03-02-chat-conversational-interface.md is complete and sufficient: search_research(query, tags, limit) for ranked discovery, get_research_item(slug) for full content retrieval, and get_related_items(slug) for cross-reference navigation via state/links.json. [High confidence]

4. The CLI research search command is designed in 2026-03-02-semantic-full-text-search.md with SQLite FTS5 index, mtime-based rebuild, and --limit/--mode/--tag options, but is not yet implemented in src/main.py. [High confidence]

5. The email digest path via the davidamitchell/Latest-developments- pattern requires at minimum two new credentials (RESEND_API_KEY and EMAIL_RECIPIENT) that do not appear in the approved credentials table, making it a hard-stop blocked item under the non-negotiable constraints. [High confidence]

6. Outbound Slack notification (one completed item per push) is low-complexity — four lines of workflow YAML Ain't Markup Language (YAML) using slackapi/slack-github-action@v2.1.1 — but is equally blocked pending explicit owner approval of the SLACK_WEBHOOK_URL secret. [High confidence]

7. The human and agent consumers have structurally different access patterns: the human researcher performs discovery (browsing by date and tag), while the AI agent performs retrieval (querying by keyword to locate specific items for synthesis); no single interface serves both optimally, making the two-layer strategy the correct design. [Medium confidence — inference from usage patterns]

8. All currently unblocked interface channels (wiki, MCP server, CLI search command) incur zero ongoing cost — they rely on GITHUB_TOKEN and local file access with no paid API calls. [High confidence]

9. The MCP server implementation must be accompanied by an Architecture Decision Record (ADR) documenting the stdio transport choice, three-tool interface contract, grounding design (tool-scoped retrieval prevents corpus hallucination), and the Phase 1 (grep) / Phase 2 (FTS5) phasing. [High confidence — per 2026-03-02-chat-conversational-interface.md Key Finding #10]

10. iOS Shortcuts provide a complementary mobile-access layer: a "Open URLs" shortcut points to the wiki Home page for read access, and a GitHub Issues API shortcut handles mobile research capture — neither requires any server-side changes. [High confidence]

Identified but not consulted:

• [ ] davidamitchell/Latest-developments- source code (src/) — README was sufficient to characterise the pattern; full source not required for this finding
• [ ] MCP HTTP/SSE transport specification — not relevant since stdio transport is the confirmed choice

Assumptions

• Assumption: The owner has not approved SLACK_WEBHOOK_URL, RESEND_API_KEY, or EMAIL_RECIPIENT credentials since the 2026-03-02-slack-msteams-research-integration.md item was completed. Justification: The approved credentials table in .github/copilot-instructions.md lists only four credentials; no subsequent session log mentions a table update. If these credentials have since been approved, the blocked items are immediately actionable.

Analysis

The interface strategy is architecturally complete, with two channels live or fully designed and two channels blocked by credential constraints. The key trade-off evaluated was human-browsing vs agent-query vs push-notification: they are not competing designs but complementary layers targeting distinct consumer modes. [inference] Prioritising the MCP server over the CLI search command is correct because it serves agent-to-corpus queries, which is the higher-frequency use case during research loop sessions. The CLI search command is a useful supplement that shares the FTS5 backend and should be implemented in the same slice. Push notifications (Slack/email) add value but are optional and blocked — delaying them costs nothing.

The email digest pattern from Latest-developments- is well-established but architecturally heavier than needed: that project watches external feeds and produces AI summaries, whereas a research digest only needs to list recently completed items. If credentials are approved, the digest workflow would be simpler than the Latest-developments- pipeline — a schedule-triggered workflow that reads completed dates from Research/completed/ YAML Ain't Markup Language (YAML) front-matter and posts a summary.

Risks, Gaps, and Uncertainties

• Credential approval is the single unresolved variable. Email digest and Slack notification are architecturally ready but blocked until the owner approves the relevant credentials. No technical gap; the gap is administrative.
• MCP server Phase 2 depends on semantic-full-text-search.md implementation. Phase 1 (grep-based) is independent and deployable now. If the FTS5 search layer is delayed, Phase 1 is fully functional.
• get_related_items depends on state/links.json population, which in turn depends on 2026-03-03-knowledge-linking-connected-corpus.md being implemented. Without that edge store, the tool returns empty results rather than an error.
• Wiki navigation is flat. The GitHub wiki has no subdirectory support, so as the corpus grows beyond ~200 items, the Home.md index may become long. Tag-based grouping in _Sidebar.md mitigates this but does not resolve it. A future item could address hierarchical navigation.

Open Questions

1. Should a research digest CLI command be added that generates a Markdown summary of the last N days' completions, usable both locally and as a workflow step? This would be a lightweight alternative to the email digest for producing a shareable briefing without external credentials. Priority: low (no downstream blocker).

2. When the owner approves email or Slack credentials, should the notification and digest be a separate new workflow file or merged into publish-wiki.yml? The trigger (push to main touching Research/completed/**) is the same; merging reduces workflow count. Priority: low; decide at implementation time.

sources

• [x] davidamitchell/Latest-developments- — email digest pattern (consulted: README.md)
• [x] MCP tool creation docs — (consulted)
• [x] Research/completed/2026-03-01-github-wiki-research-content.md — wiki delivery channel (prior art)
• [x] Research/completed/2026-03-02-chat-conversational-interface.md — MCP server design for agent query (prior art)
• [x] Research/completed/2026-03-02-slack-msteams-research-integration.md — push notification options (prior art)
• [x] Research/completed/2026-03-02-ios-shortcuts-research.md — iOS/mobile access patterns (prior art)
• [x] Research/completed/2026-03-02-semantic-full-text-search.md — CLI search command design (prior art)