gistfile1.txt

# SpecLedger Telegram Bot — User Guide

## Overview

The SpecLedger Telegram Bot bridges your team's Telegram conversations with your GitHub-hosted specs and issues. Use it to capture meeting decisions directly into specs, create issues from discussions, and get notified when specs change — all without leaving Telegram.

---

## Getting Started

### 1. Register Your Account

Each team member must link their Telegram account to SpecLedger:

```
/register
```

The bot will walk you through authentication. This is a one-time step. Use `/unregister` to unlink later.

### 2. Connect Your Chat to a Project

In the group chat (or private chat) where your team discusses the project, connect it to a GitHub repository:

```
/connect acme/mobile-app
```

Once connected, all commands in that chat default to the connected repo — no need to type `owner/repo` every time.

To disconnect later:

```
/disconnect
```

---

## Synchronizing Specs from Meetings

This is the primary workflow for turning meeting discussions into spec updates.

### How It Works

1. Your team has a meeting (voice call, in-person, or text discussion)
2. Someone posts the meeting summary or notes into Telegram
3. Run `/digest` to have the bot analyze the notes
4. The bot extracts decisions, requirements, and action items
5. It distributes updates to the relevant spec files and creates issues as needed

### Step-by-Step

**Start a digest session:**

```
/digest
```

Or if the chat is not connected to a project:

```
/digest acme/mobile-app
```

**Post your meeting notes.** You can paste a summary, forward messages, or type notes directly. The bot listens to all messages after `/digest` is called. Example:

> We decided to add biometric login for the iOS app. The design system needs a new FaceIDPrompt component. John will handle the backend token refresh. Target: next sprint.

**End the session:**

```
/done
```

The bot then:
- Identifies which specs are affected
- Proposes updates to the relevant `spec.md` files
- Creates issues for action items it detects
- Asks for confirmation before committing changes

### Tips for Better Digests

- **Be explicit about decisions.** "We decided X" is clearer than "we talked about X."
- **Name features.** Reference spec names or branch numbers (e.g., "597-mockup-generation") so the bot can match them accurately.
- **Separate topics.** If you discussed multiple features, label them. The bot handles multi-topic notes, but clear structure helps.
- **Paste the meeting summary directly** rather than describing it second-hand.

---

## Creating Issues from Discussions

When a discussion surfaces a bug, task, or feature request, create an issue immediately:

```
/issue bug Login crashes when session token expires during biometric auth
```

Or with explicit repo:

```
/issue acme/mobile-app feature Add haptic feedback to the checkout button
```

**Supported issue types:** `bug`, `feature`, `task`

The bot creates the GitHub issue and returns a link. No context-switching needed.

---

## Watching Specs for Updates

Stay informed when pull requests modify specs you care about.

**Watch a spec:**

```
/watch 597-mockup-generation
```

Or with explicit repo:

```
/watch acme/mobile-app 597-mockup-generation
```

**Stop watching:**

```
/unwatch 597-mockup-generation
```

**See everything you're watching:**

```
/watching
```

When a PR touches a watched spec, the bot sends you a notification with the PR link, changed sections, and a summary of what was modified.

---

## Typical Team Workflow

```
Monday standup (Telegram group)
  │
  ├─ Team discusses features and blockers
  ├─ Someone runs /digest
  ├─ Notes are posted during discussion
  ├─ /done → bot updates specs, creates issues
  │
  ├─ PM creates a new issue:  /issue task Update onboarding copy
  │
  └─ Engineers watch their specs:  /watch 597-mockup-generation
       └─ Get notified when PRs land
```

---

## Quick Reference

| Task                           | Command                               |
| ------------------------------ | ------------------------------------- |
| Register                       | `/register`                           |
| Connect chat to repo           | `/connect owner/repo`                 |
| Start meeting digest           | `/digest`                             |
| Finish digest and process      | `/done`                               |
| Create an issue                | `/issue type description`             |
| Watch a spec                   | `/watch spec-key`                     |
| Stop watching                  | `/unwatch spec-key`                   |
| List watched specs             | `/watching`                           |
| Disconnect chat                | `/disconnect`                         |
| Unregister                     | `/unregister`                         |