Engineering manager 1-on-1 meeting brief generator

Overview

PullStar fetches GitHub activity for one engineer (PRs authored, reviews given), runs a deterministic local scoring engine across five dimensions, and prepares an LLM input payload. The agent then performs LLM inference and finalizes the brief.

Quickstart:

run_brief.py --login steipete --pr-insights --days 7
Read llm_input_steipete.json, do the LLM inference, present the brief

Data Flow Summary:

⚠️ Important: Steps 1–3 run locally. Only the LLM inference step (step 4) sends data to your AI provider.

---

Requirements

• Python 3.11+
• Install dependencies: pip install PyGithub python-dotenv requests
• A GitHub personal access token (see Security section below)

---

Security & Privacy

Token Scope

Fine-grained PATs cannot search across arbitrary users. Use a classic PAT for org-wide briefs.

Set GITHUB_ORG to narrow search to one organization.

Token Resolution Order

Secrets are resolved using layered lookup — first match wins:

1. --github-token CLI flag (override/debug only — never logged)
2. GITHUB_TOKEN environment variable
3. ~/.pullstar/credentials (key=value format)
4. .env in the skill directory

Data Privacy by Mode

Default (no --pr-insights):

• Only aggregated statistics and scores sent to LLM
• No raw PR text, comments, or review bodies included

PR Insights (--pr-insights):

• Bounded raw PR discussion text packaged into the LLM prompt
• Bounded to 5 PRs, 3 reviews/comments each, 600 char limit per item
• Review llm_input_{login}.json before inference if you have privacy concerns

---

Configuration

.env

---

Usage

Standard run

python run_brief.py --login jsmith

With PR insights

python run_brief.py --login jsmith --pr-insights

Common options

python run_brief.py --login jsmith --days 14          # wider lookback (default: 5)
python run_brief.py --login jsmith --max-results 10   # faster on high-activity users (default: 20)
python run_brief.py --login jsmith --api-mode rest    # force REST API (default: graphql)

All options

---

Agent Flow

run_brief.py runs the deterministic pipeline (ingest → score → prepare) and then prints an explicit instruction block. The agent must complete the final two steps:

============================================================
PIPELINE COMPLETE — AGENT ACTION REQUIRED
============================================================

  1. Read:   .pullstar/llm_input_jsmith.json
  2. Extract the "system" and "user" fields
  3. Call your LLM with those as the system prompt and user message
  4. Write the response to .pullstar/llm_output_jsmith.json
  5. Run:    python scripts/agent_finalize_1on1.py --login jsmith

---

Agent JSON Contract

Input (from run_brief.py)

File: .pullstar/llm_input_{login}.json

Output (from agent)

File: .pullstar/llm_output_{login}.json

{
  "version":        "1.0",
  "engineer_login": "jsmith",
  "brief":          "## Quick Summary\n..."
}

Requirements:

• Valid JSON
• brief must be a non-empty markdown string
• Plain text is also accepted — the full file content will be used as the brief

---

Brief Output Format

The final brief (output_{login}.json) contains a markdown document with six sections:

Example Score Summary table:

---

Artifacts

All artifacts are written to .pullstar/ (gitignored, never committed).

---

Troubleshooting

"GitHub rejected the PR search query (422)" Use a classic PAT — fine-grained PATs cannot search across arbitrary users.

"GitHub rate limit hit" Authenticated: 5000 req/hr. Unauthenticated: 60 req/hr. Set GITHUB_TOKEN.

Slow ingestion on high-activity users Use --max-results 10 to cap iteration. Default is 20.

GraphQL errors Use --api-mode rest to fall back to the legacy REST API.

---

For Agent Developers

Subagent Best Practices (Don't Be a Nervous Parent)

When using sessions_spawn for the LLM inference step:

✅ Do:

• Spawn once with the task to read llm_input_{login}.json and write llm_output_{login}.json
• Trust the "auto-announces on completion" behavior — you'll get a completion event
• Handle the result when the event arrives

❌ Don't:

• Poll subagents list in a tight loop waiting for completion
• Spawn multiple subagents for the same task
• Check status every few seconds — it's wasteful

Why: Subagents are lightweight (no full OpenClaw context, isolated environment), but polling defeats the purpose of push-based completion. The system will tell you when it's done.

Recovery: If a subagent fails, you can always generate the brief directly in the main session — the JSON contract is simple and documented above.

---

License

MIT — See source repository for full license text.