Internal Issue Tracker

Internal Issues

An InternalIssue row lives in Slop's SQLite database. It is not a GitHub issue. Nothing about it touches the GitHub API. The only connection to a watched repo is the repoId foreign key (the owner/name slug). Internal issues appear alongside GitHub issues on the board, can be set ready, drag-reordered, and implemented by any agent harness.

Schema

HTTP API

All endpoints are served by the running Slop server (default http://localhost:3100). Source: src/app/api/internal-issues/route.ts and src/app/api/internal-issues/[id]/route.ts.

Story Points

Slop can estimate implementation complexity before dispatching an agent. The result drives automatic model and effort selection: trivial issues get a small fast model; architectural ones get a capable high-effort one. Source: src/server/runs/suggest-points.ts

The seven-tier rubric

How auto-scoring works

BMAD Story Ingestion

BMAD is an AI planning methodology that produces a PRD and a set of user story markdown files. Slop can scan a watched repo's BMAD output directory and bulk-import those stories as internal issues, turning planning artifacts into actionable implementation tasks without manual copy-paste. Source: src/lib/bmad-stories.ts src/app/api/bmad-stories/route.ts

Directory layout

BMAD writes artifacts into the watched repo at a fixed relative path:

_bmad-output/
  planning-artifacts/
    prd.md                     # parent PRD (may be nested at any depth)
  implementation-artifacts/
    story-1.1.md               # story files -- one per user story
    story-1.2.md
    story-2.1.md
    ...

Slop scans _bmad-output/implementation-artifacts/ for .md files. Each file must contain a # Story N.M: <title> heading. Files without this heading are reported as parse errors.

Story file format

A minimal story file that Slop can import:

---
id: story-1.1
title: Add user authentication
status: Approved
story_points: 5
---

# Story 1.1: Add user authentication

Status: Approved

## Goal

Implement JWT-based login so users can authenticate via `/auth/login`.

## Acceptance Criteria

- `POST /auth/login` returns a signed JWT on valid credentials
- Invalid credentials return 401
- Token claims include `userId` and `exp`

The frontmatter story_points value, if present, seeds IssueConfig.storyPoints on import, skipping the scoring agent for stories that already carry an estimate from the planning phase. The body after stripping frontmatter becomes the internal issue body.

Import API

Re-import detection

Before creating an issue, Slop checks whether any existing internal issue already carries the story's source line in its body:

Story: _bmad-output/implementation-artifacts/story-1.1.md

It also checks whether any issue title contains Story N.M: <name>. Both checks are needed because epic numbering restarts at 1.1 per PRD, so an id-only check would collide with stories from older planning runs on disk. If either check matches, the story is marked imported: true in the scan result and is not created again.

PRD discovery

Slop walks the full _bmad-output/ tree for any file named prd.md and picks the most recently modified one by mtime. The first # heading in that file (after stripping frontmatter, with any leading "PRD:" prefix removed) is used as a batch name for the import group.

Worker Report Synthesis

When a worker fails, or when the resource monitor detects a memory breach, Slop runs a short read-only agent session that diagnoses the root cause and files an internal issue on the watched repo. Failed runs become actionable items. Source: src/server/runs/worker-report-issue.ts

Trigger conditions

What the agent reads

The synthesis agent receives:

• The last 400 events from the worker's run log (level, type, message, and full rawContent for errors).
• Direct access to Slop's SQLite database via the sqlite3 CLI, including the worker's id and example queries for token/turn/cost data.
• For memory breaches: structured data with threshold, peak RSS, per-sample timeline, and per-process RSS and CPU stats.

The session is read-only against the codebase. The agent reads source files to understand root causes. It never writes to the repo.

Filed issue format

The agent must reply with exactly one fenced slop-issue block:

```slop-issue
{"title": "permission denied on git push wasted 12 turns",
 "body": "## Token usage\n38k in / 9k out across 22 turns...\n\n## Findings\n...\n\n## Recommendations\n..."}
```

Slop parses this block, prefixes the title with ralph: (unless already present), and files the issue via createInternalIssue. An empty title causes the run to complete without filing.

The feedback loop

Every filed diagnostic issue is a first-class internal issue on the board. The loop is self-improving:

issueSource: GitHub vs. Internal

The issueSource field appears on three tables: Worker, ReadyIssue, and ReadyOrder. Its value is either "github" or "internal". The default is "github".

Why it exists

GitHub issue numbers and internal issue numbers are both integers starting at 1, incrementing independently per repo. Without issueSource, GitHub issue #5 and internal issue #5 would be indistinguishable in the database. The unique constraint on Worker is:

@@unique([repoId, issueSource, issueNumber])

This means a GitHub issue #5 and an internal issue #5 can each have an active worker at the same time, with no conflict.

How it flows through the system