Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions migrations/0006_feedback_inbox.sql
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
-- Feedback & Bug Inbox: stores raw feedback and bug observations per team and optional repository hint.

CREATE TABLE feedback_notes (
id TEXT PRIMARY KEY,
team_id TEXT NOT NULL REFERENCES teams(id),
author_membership_id TEXT NOT NULL REFERENCES memberships(id),
repo_hint TEXT,
raw_text TEXT NOT NULL,
source_type TEXT NOT NULL DEFAULT 'text' CHECK (source_type IN ('text', 'voice')),
status TEXT NOT NULL DEFAULT 'inbox' CHECK (status IN ('inbox', 'triaged', 'archived')),
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL
);

CREATE INDEX idx_feedback_notes_team_status ON feedback_notes(team_id, status);
CREATE INDEX idx_feedback_notes_team_repo ON feedback_notes(team_id, repo_hint);
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-19
85 changes: 85 additions & 0 deletions openspec/changes/archive/2026-10-19-feedback-inbox/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
## Context

See `proposal.md` for motivation. The bot runs on Cloudflare Workers with Hono, grammY, D1 storage, and Workers AI. All tenant-scoped operations mandate `TeamId` as the first argument in domain ports. The Natural Language pipeline (`handle-natural-language.ts`) classifies user utterances into a closed set of intents using `@cf/meta/llama-3.1-8b-instruct`. Cloudflare Workers AI natively supports `@cf/openai/whisper-large-v3-turbo` for speech-to-text.

## Goals / Non-Goals

**Goals:**
- Provide team-scoped storage for raw bug reports, feedback, and demo observations in Cloudflare D1.
- Support both text messages and Telegram voice notes (`message:voice`), transcribing audio with Whisper before passing it to the intent classifier.
- Implement an adaptive, state-driven synthesis strategy: summarize whatever is pending in `status = 'inbox'`, reporting the real-world date range spanned, with optional natural language date narrowing.
- Provide AI-assisted synthesis of collected notes into a consolidated issue-ready briefing using Workers AI.
- Enable marking notes as `triaged` or `archived` so the inbox resets for future sessions.

**Non-Goals:**
- Direct GitHub issue creation or mutation (remains the responsibility of local development workflows and CLI tools).
- Bot audio voice replies (text replies only).
- Public/unauthenticated feedback endpoints.

## Decisions

### Decision 1: Voice Note Pipeline via Whisper STT

When grammY receives an eligible `message:voice`, the flow is:
1. `TelegramVoiceFetcher` uses `ctx.api.getFile(voice.file_id)` to resolve the download URL and fetches the raw audio buffer (OGG/Opus).
2. `SpeechToText` port calls Cloudflare Workers AI:
```typescript
const response = await env.AI.run("@cf/openai/whisper-large-v3-turbo", {
audio: [...new Uint8Array(audioBuffer)],
});
```
3. The resulting transcript text is passed directly into `handleNaturalLanguage({ classifiedText: transcript.text, ... })`.

*Alternatives considered*:
- Using an external transcription API (e.g. OpenAI Whisper API): Rejected to avoid external API keys and latency; Cloudflare Workers AI runs within the worker's execution environment.

### Decision 2: D1 Table Schema for Feedback Notes

The new table `feedback_notes` follows multi-tenant architecture with strict `team_id` partitioning:

```sql
CREATE TABLE feedback_notes (
id TEXT PRIMARY KEY,
team_id TEXT NOT NULL REFERENCES teams(id),
author_membership_id TEXT NOT NULL REFERENCES memberships(id),
repo_hint TEXT,
raw_text TEXT NOT NULL,
source_type TEXT NOT NULL DEFAULT 'text', -- 'text' | 'voice'
status TEXT NOT NULL DEFAULT 'inbox', -- 'inbox' | 'triaged' | 'archived'
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL
);

CREATE INDEX idx_feedback_notes_team_status ON feedback_notes(team_id, status);
CREATE INDEX idx_feedback_notes_team_repo ON feedback_notes(team_id, repo_hint);
```

### Decision 3: Adaptive State-Driven Synthesis Strategy

Instead of rigid calendar jobs (e.g., daily cron summaries), the synthesis operates on **unprocessed inbox state**:
- **Query**: Select notes matching `team_id`, `status = 'inbox'`, and matching `repo_hint` (if specified), ordered by `created_at ASC` up to 30 notes.
- **Date Span Metadata**: The use case extracts `min(created_at)` and `max(created_at)` from the matched set and formats the header (e.g., *"Resumen de 7 observaciones (12/10 al 19/10)"*).
- **Temporal Narrowing (Optional)**: If the user says *"resumen de hoy"* or *"resumen de esta semana"*, a `sinceTimestamp` filter is applied over the pending notes.
- **Triage Transition**: After a summary is reviewed, a member can mark the batch as processed (`archive_feedback`), moving their status to `triaged`.

### Decision 4: Hexagonal Domain Ports & Use Cases

Isolate storage and AI dependencies behind domain ports:
- `FeedbackRepo`:
- `save(teamId: TeamId, note: FeedbackNote): Promise<void>`
- `list(teamId: TeamId, filter: FeedbackFilter): Promise<FeedbackNote[]>`
- `updateStatus(teamId: TeamId, noteIds: string[], status: FeedbackStatus): Promise<void>`
- `SpeechToText`:
- `transcribe(audioBuffer: ArrayBuffer, signal: AbortSignal): Promise<string>`
- `FeedbackSynthesizer`:
- `synthesize(notes: FeedbackNote[], signal: AbortSignal): Promise<FeedbackSummary>`
- Domain use cases:
- `record-feedback.ts`: Validates caller membership, derives repo hint from topic context if omitted, and saves note.
- `list-feedback.ts`: Retrieves active notes for the team/repo.
- `synthesize-feedback.ts`: Loads active notes and formats them via `FeedbackSynthesizer`.
- `archive-feedback.ts`: Marks processed notes as `triaged`.

## Risks / Trade-offs

- **[Risk] Ambient noise in voice notes during live demos** → *Mitigation*: Whisper STT handles background chatter robustly; if confidence/length is below threshold, the bot returns a friendly error asking to re-record or type.
- **[Risk] Irregular activity creating huge note batches** → *Mitigation*: Synthesis is capped at 30 notes per batch, ensuring responses comfortably fit within the Workers AI context window and Telegram's 4096-character limit.
36 changes: 36 additions & 0 deletions openspec/changes/archive/2026-10-19-feedback-inbox/proposal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
## Why

During live demos, hackathons, and mobile testing, developers and team members encounter bugs and receive user feedback away from their development machines. Opening formal GitHub issues immediately is high-friction, leads to duplicate or poorly structured issues, and violates repository contribution standards. Furthermore, typing long bug descriptions on mobile during a demo is cumbersome compared to sending a quick voice message.

This change introduces an in-chat feedback and bug inbox for Hack-bot, allowing team members to record raw observations and feedback via text or voice messages (transcribed with Whisper on Cloudflare Workers AI), store them per team and target repository, and synthesize all unprocessed inbox notes into consolidated briefings on demand.

## What Changes

- Add voice note transcription support to the natural language pipeline using Cloudflare Workers AI (`@cf/openai/whisper-large-v3-turbo`) so voice messages in Telegram are transcribed and routed seamlessly through the natural language intents.
- Add a new `feedback-inbox` domain capability and D1 storage table (`feedback_notes`) to store raw bug reports, feedback, and demo observations.
- Associate notes with the originating team, author (membership), target repository hint (if mentioned or inferred from topic), status (`inbox`, `triaged`, `archived`), and timestamp.
- Implement an adaptive, state-driven synthesis strategy: rather than relying on arbitrary daily or weekly calendar buckets, the synthesis operates on all pending notes (`status = 'inbox'`) regardless of elapsed time, indicating the actual date span covered, while optionally respecting natural language temporal requests (e.g., "resumen de hoy").
- Extend natural language classification (`natural-language-text`) with new intents:
- `capture_feedback`: parse raw report text, optional repo hint, and tags.
- `list_feedback`: list recent unprocessed feedback notes for a team/repo.
- `summarize_feedback`: invoke LLM extraction to synthesize unprocessed notes into a structured briefing ready for GitHub issue creation.
- `archive_feedback`: mark notes or a summarized batch as triaged/archived.
- Add copy strings for feedback intake confirmation, listings, and summary presentation in `bot-copy`.

## Capabilities

### New Capabilities

- `feedback-inbox`: Captures, queries, and manages raw feedback and bug observations in team-scoped storage, providing state-driven retrieval and AI-assisted synthesis of grouped observations without directly mutating GitHub.

### Modified Capabilities

- `natural-language-text`: Adds voice message transcription (`message:voice`) using Whisper STT and adds intent recognition and slot extraction for `capture_feedback`, `list_feedback`, `summarize_feedback`, and `archive_feedback` intents.
- `bot-copy`: Adds bot response copy for feedback intake acknowledgment, note listings, date-ranged summaries, and triaged status confirmations.

## Impact

- **Database**: New migration adding `feedback_notes` table with indexes on `(team_id, status)` and `(team_id, repo_hint)`.
- **Domain**: New ports and use cases for audio transcription, feedback recording, listing, status updates, and summary generation.
- **Adapters**: Telegram voice file download adapter, Cloudflare Workers AI Whisper STT adapter, D1 repository adapter for feedback notes, grammar/intent classifier updates for Workers AI.
- **Dependencies**: No new external dependencies; reuses existing Cloudflare Workers AI (`@cf/openai/whisper-large-v3-turbo` and `@cf/meta/llama-3.1-8b-instruct`) and D1 infrastructure.
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
## ADDED Requirements

### Requirement: Feedback Inbox Copy Formatting

The system MUST format all feedback intake confirmations, voice transcription messages, feedback listings, and synthesized summaries in neutral, professional Spanish without raw JSON or unmapped technical error codes, and within the 4096-character Telegram limit.

#### Scenario: Feedback intake confirmation in Spanish
- **WHEN** a feedback note is stored
- **THEN** the confirmation message is sent in Spanish indicating that the observation was recorded in the inbox

#### Scenario: Feedback summary formatting with date span
- **WHEN** a feedback synthesis briefing is rendered for Telegram
- **THEN** the header specifies the total count and date span of the included notes (e.g. "Resumen de 5 observaciones entre el 12/10 y el 19/10")
- **AND** all section headers, labels, and bullet points are presented in clean Spanish text
- **AND** fits within the Telegram length limits

#### Scenario: Audio transcription failure copy
- **WHEN** a voice message cannot be transcribed due to noise or model failure
- **THEN** the bot responds with a friendly Spanish message indicating the audio could not be understood and requesting a repeat or text input
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
## Purpose

Provides a tenant-scoped feedback and bug observation inbox where team members capture unstructured notes via Telegram (text or voice), retrieve pending observations, and generate consolidated briefings without directly altering GitHub repositories.

## ADDED Requirements

### Requirement: Record Feedback and Bug Observations

The system MUST allow authenticated team members to record raw feedback or bug observations scoped to their team, submitted as text or transcribed voice messages. Each note MUST store the raw text, the author's membership identifier, the timestamp of submission, an optional target repository hint, and an initial status of `inbox`.

#### Scenario: Successfully capture a bug note with repository hint
- **WHEN** a team member records a note mentioning an explicit repository hint (e.g. `puls3`)
- **THEN** the system stores the observation in the team's inbox with `repo_hint` set to `puls3`
- **AND** sets status to `inbox`
- **AND** responds with an acknowledgment message confirming the note is recorded

#### Scenario: Successfully capture general feedback without repository hint
- **WHEN** a team member records feedback without mentioning any repository
- **THEN** the system stores the observation with `repo_hint` set to null
- **AND** sets status to `inbox`
- **AND** acknowledges receipt

#### Scenario: Non-member cannot record feedback
- **WHEN** a user who is not a registered member of the team attempts to record a note
- **THEN** the system rejects the operation
- **AND** does not persist any observation

### Requirement: Query Feedback Notes

The system MUST allow team members to list stored feedback notes for their team, optionally filtered by status (`inbox`, `triaged`, `archived`) and by target repository hint.

#### Scenario: List active inbox notes
- **WHEN** a team member requests the list of pending feedback
- **THEN** the system returns all notes with status `inbox` for that team ordered by creation time descending
- **AND** limits the output to fit within Telegram message limits

#### Scenario: Empty inbox returns designated notification
- **WHEN** a team member requests pending feedback but no notes exist in `inbox` status
- **THEN** the system returns a friendly message stating that the inbox is empty

### Requirement: Adaptive State-Driven Feedback Synthesis

The system MUST allow team members to trigger an AI-assisted synthesis of feedback notes. By default, the synthesis MUST operate on all pending notes (`status = 'inbox'`) regardless of elapsed days or intervals between notes, explicitly stating the start and end dates of the included observations. If the user specifies a natural language time window (e.g. "de hoy", "de esta semana"), the synthesis MUST narrow the selected inbox notes to that window. The output MUST group duplicate or related observations, highlight severity or impact, and format actionable suggestions ready for issue drafting, without mutating GitHub.

#### Scenario: Synthesize pending notes across irregular intervals
- **WHEN** a team member requests a summary of feedback for a repository
- **AND** the inbox contains pending notes spanning multiple days or weeks with dormant gaps
- **THEN** the system aggregates all pending notes for that repository
- **AND** generates a structured summary indicating the date span of the aggregated notes
- **AND** does not create any GitHub issues or mutate remote repositories

#### Scenario: Synthesize with temporal narrowing filter
- **WHEN** a team member explicitly asks for a summary "de hoy" or "de esta semana"
- **THEN** the system filters pending notes matching the requested time window
- **AND** generates the summary for that subset

#### Scenario: Synthesize with no notes available
- **WHEN** a team member requests a summary for a repository that has no recorded notes in the target scope
- **THEN** the system informs the caller that there are no observations to synthesize

### Requirement: Triage and Archive Feedback Notes

The system MUST allow team members to mark individual feedback notes or an entire synthesized batch as `triaged` or `archived`, removing them from the active pending inbox.

#### Scenario: Mark note as triaged
- **WHEN** a team member marks a note ID as triaged
- **THEN** the system updates its status to `triaged`
- **AND** confirms the update to the user
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
## MODIFIED Requirements

### Requirement: Group-Only Eligible Delivery

The system MUST accept natural-language handling only in group or supergroup chats (General and topics). The system MUST NOT run the NL path for private (DM) chats. Under Telegram privacy mode, an eligible NL message MUST be either (a) text or voice that `@`-mentions the bot username from `BOT_INFO`, or (b) a text or voice reply to a message authored by the bot. Other plain-text group messages MUST be ignored without error. When an eligible message is a voice note (`message:voice`), the system MUST transcribe the audio to text via Whisper Speech-to-Text before passing the transcribed text to intent classification. Recognized bot commands MUST continue to use the command handlers and MUST NOT also be classified as NL.

#### Scenario: @mention in General is eligible

- GIVEN a registered team group and the bot username from `BOT_INFO`
- WHEN a member sends a message that `@`-mentions that username followed by `qué hackathons hay` in General
- THEN the system enters the NL path

#### Scenario: Reply to bot in a topic is eligible

- GIVEN a forum topic in a registered team group
- WHEN a member replies to a bot message with `listá los repos`
- THEN the system enters the NL path

#### Scenario: Plain text without mention or reply is ignored

- GIVEN a registered team group
- WHEN a member sends `qué hackathons hay` without mentioning the bot and not as a reply to the bot
- THEN the system ignores the update without invoking the NL classifier

#### Scenario: DM is ignored by NL

- GIVEN a private chat with the bot
- WHEN the user `@`-mentions the bot username from `BOT_INFO` and asks for help
- THEN the system MUST NOT run the NL path

#### Scenario: Commands are not double-handled

- GIVEN a group message `/hackathons`
- WHEN the update is processed
- THEN the existing command handler runs
- AND the NL classifier is NOT called

#### Scenario: Voice note mentioning the bot is transcribed and handled

- GIVEN an eligible voice note in a group chat mentioning the bot or replying to a bot message
- WHEN the update is received
- THEN the system downloads the voice note audio
- AND transcribes it via Whisper STT
- AND passes the transcribed text to the NL classifier

### Requirement: Closed Intent Coverage

The system MUST classify eligible Spanish utterances into a closed intent set that covers every existing group capability: `help`, `setup_team`, `join_team`, `bind_data_channel`, `show_profiles`, `set_profile_field`, `promote_member`, `demote_member`, `link_repo`, `unlink_repo`, `list_repos`, `list_hackathons`, `show_hackathon`, `link_hackathon_topic`, `unlink_hackathon_topic`, `request_hackathon_analysis`, `show_topic_hackathon`, `participate_hackathon`, `capture_feedback`, `list_feedback`, `summarize_feedback`, `archive_feedback`, and `unknown`. Each non-`help`/`unknown` intent MUST dispatch to the same domain use case (or equivalent path) the matching slash command uses today, with the same authorization rules.

#### Scenario: List hackathons via NL

- GIVEN an eligible utterance classified as `list_hackathons` with sufficient confidence
- WHEN the member is a team member
- THEN the system replies with the same listing behavior as `/hackathons`

#### Scenario: Unknown intent

- GIVEN the classifier returns `unknown` or confidence below the design floor (0.55)
- WHEN the utterance is processed
- THEN the system replies with the unknown copy and performs no side effect

#### Scenario: Capture feedback via NL

- GIVEN an eligible utterance describing a bug, issue, or feedback classified as `capture_feedback`
- WHEN the caller is an authenticated team member
- THEN the system records the feedback note in the team inbox

#### Scenario: List feedback via NL

- GIVEN an eligible utterance requesting pending feedback classified as `list_feedback`
- WHEN the caller is an authenticated team member
- THEN the system replies with active feedback notes

#### Scenario: Summarize feedback via NL

- GIVEN an eligible utterance requesting a summary or synthesis of feedback classified as `summarize_feedback`
- WHEN the caller is an authenticated team member
- THEN the system synthesizes pending inbox observations and replies with the briefing

#### Scenario: Archive feedback via NL

- GIVEN an eligible utterance requesting to triage or archive feedback classified as `archive_feedback`
- WHEN the caller is an authenticated team member
- THEN the system updates the status of the target notes to `triaged`
Loading
Loading