/bip.narrative

Generate a themed narrative digest for a Slack channel.

Usage

/bip.narrative <channel> [--since <period>] [--verbose]

Arguments:

• <channel>

  — Channel name (required, e.g.,

  dasm2

  )

• --since <period>

  — Time period to cover (default:

  1w

  ). Examples:

  1w

  ,

  2d

  ,

  3d

• --verbose

  — Include PR/issue body summaries in the raw activity

Setup

The nexus path is configured in

~/.config/bip/config.json

. For the commands below, use the configured path (e.g., if

nexus_path

is

~/re/nexus

, substitute that).

Workflow

Execute these steps in order:

Step 1: Fetch Raw Activity

Run the bip digest command to get GitHub activity:

bip digest --channel {{channel}} --since {{since}} {{verbose_flag}}

Where:

• {{channel}}

  is the channel argument

• {{since}}

  defaults to

  1w

  if not specified

• {{verbose_flag}}

  is

  --verbose

  if the user passed that flag, otherwise empty

If the command fails or returns no activity, stop and report "No activity found for channel {{channel}} in the specified period."

Step 2: Read Shared Preferences

Read the shared preferences file:

cat <nexus>/narrative/preferences.md

If the file doesn't exist, stop and report: "Missing shared preferences file: <nexus>/narrative/preferences.md"

Step 3: Read Channel Configuration

Read the channel-specific config:

cat <nexus>/narrative/{{channel}}.md

If the file doesn't exist, stop and report: "Missing channel config: <nexus>/narrative/{{channel}}.md Create this file with Themes and Repo Context sections."

Step 4: Generate Narrative

Using the raw activity from Step 1, the preferences from Step 2, and the channel config from Step 3, generate a narrative digest following these rules:

Structure:

1. Start with header:

   # {{channel}} Digest: {{date_range}}

   • Date range should match the

     bip digest

     output (e.g., "Jan 18-25, 2026")
2. Organize content by themes from the channel config's

   ## Themes

   section
3. End with a

   ## Looking Ahead

   section for open items

Theme Classification:

• Read the themes from the channel config's

  ## Themes

  section
• Assign each activity item to the most appropriate theme
• Only include themes that have activity
• Theme order follows the numbered list in the config

Subheadings (if applicable):

• Check the channel config's

  ## Project-Specific Preferences

  section
• If it specifies subheadings (like "viral/antibody paragraphs"), use those within theme sections
• Subheadings are channel-specific—only use what the config specifies

Formatting (Hybrid Style):

• Use prose when describing connected work or narrative flow
• Use bullets for lists of discrete items or contributors
• Status prefixes for non-merged items:

  • In progress:

    for open PRs

  • Open:

    for open issues
• CRITICAL: Every PR/issue mentioned MUST have a link — never refer to work without its

  [#N](url)

  link inline
  • Bad: "A modular dataset registry was merged"
  • Good: "A modular dataset registry was merged (#176)"

Looking Ahead Section:

• Focus on open issues only (not PRs, unless a PR directly addresses a new issue worth explaining)
• Use prose style, not bullets—this section introduces new material to readers
• Provide substantial detail: explain what the issue is about, why it matters, and what needs to happen
• Group related issues together in coherent paragraphs
• Omit this section if no open issues exist

Content Guidelines (from preferences.md):

• Follow all rules in the shared preferences file
• Typically includes: no attribution, factual descriptions only
• Stick to available information—do not invent context

CRITICAL — Include ALL Activity:

• You MUST include EVERY item from the raw activity output. Do NOT skip or omit ANY PR or issue.
• EVERY repository that appears in the raw output MUST be represented in the narrative.
• If a repo has activity, it MUST appear somewhere in the digest. Missing repos is a failure.
• When in doubt, include the item. Completeness is more important than brevity.

Step 5: Write Output

Determine output path:

<nexus>/narrative/{{channel}}/{{YYYY-MM-DD}}.md

Where

{{YYYY-MM-DD}}

is today's date.

1. Create the directory if needed:

   mkdir -p <nexus>/narrative/{{channel}}

2. Write the generated narrative to the file
3. Open the file for review:

   zed <nexus>/narrative/{{channel}}/{{YYYY-MM-DD}}.md

4. Report success: "Narrative digest written to: narrative/{{channel}}/{{YYYY-MM-DD}}.md"

Step 6: Ask About Posting to Slack

After the user has reviewed the narrative, ask if they want to post it to Slack.

If user approves:

1. Commit and push the narrative:

   cd <nexus>
   git add narrative/{{channel}}/{{YYYY-MM-DD}}.md
   git commit -m "Add {{channel}} narrative digest for {{date_range}}"
   git push
   

2. Post to Slack using

   bip digest --post

   :

   bip digest --channel {{channel}} --post
   

   The webhook URL comes from

   slack_webhooks

   in

   ~/.config/bip/config.json

   or

   SLACK_WEBHOOK_{{CHANNEL_UPPER}}

   env var.

3. Report: "Posted to #{{channel}} with link to narrative."

If user declines: Report "Narrative saved but not posted."

Example Output

# dasm2 Digest: Jan 18-25, 2026

## Model Architecture

The training pipeline saw significant improvements this week. The structure-aware loss function was merged ([#142](url)), enabling better handling of hierarchical outputs. In progress: refactoring the attention mechanism for memory efficiency ([#147](url)).

## Data Processing

**Viral:**
New preprocessing filters were added for low-quality sequences ([#138](url)).

**Antibody:**
The germline alignment step now handles ambiguous calls gracefully ([#151](url)).

## Looking Ahead

Several architectural decisions are pending. The OOM issues on large batches ([#156](url)) need investigation—this is blocking production use on full-size datasets. Separately, the team is considering whether to refactor the attention mechanism for memory efficiency, which would enable scaling to longer sequences without proportional memory growth.

Error Handling

• Missing config file: Report which file is missing and stop
• No activity: Report "No activity found" and stop
• bip CLI fails: Report the error and stop
• Output directory creation fails: Report the error and stop