skills.rest
lablup
lablupOFFICIAL
Explore all skills by this author →
WebsiteGitHub

bep-guide

Guides writing and managing Backend.AI Enhancement Proposals with structured workflows.

672|181|Updated Oct 6, 2016
Search Tags:#decision log#Technical Writing#Documentation#bep#ARCHITECTURE#Backend.AI#design proposal
One-click install
npx skills add https://github.com/lablup/backend.ai --skill bep-guide
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: bep-guide
Source: https://github.com/lablup/backend.ai/tree/main/.claude/skills/bep-guide
Command: npx skills add https://github.com/lablup/backend.ai --skill bep-guide

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Writing large design proposals for Backend.AI often leads to inconsistent structure, missing decisions, and documents too long for reviewers or AI agents to navigate. This Skill standardizes how BEPs (Backend.AI Enhancement Proposals) are created, segmented, and maintained.

Core Features & Use Cases

  • End-to-End BEP Workflow: Covers number reservation, JIRA issue creation, branch naming, metadata frontmatter, section-by-section writing guidance, and PR submission.
  • Document Segmentation: Splits BEPs over 500 lines into a concise main document plus per-component sub-documents with a document index.
  • AI Context Blocks: Defines context-for-ai comment blocks so AI agents can quickly parse scope, constraints, and decisions without reading entire documents.
  • Use Case: An engineer planning a scheduler change reserves BEP-1046, writes a segmented proposal with a Decision Log, and later assigns an AI agent to implement Phase 1 by reading only the relevant sub-documents.

Quick Start

Ask the AI to create a new BEP for your proposed feature following the bep-guide workflow, starting by reserving a number in the proposals registry.

Frequently Asked Questions about bep-guide

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a BEP for Backend.AI?▼

Reserve a number in the proposals/README.md registry, create a JIRA issue, copy the BEP-0000 template, fill in the metadata frontmatter, and write sections in order: Motivation, Current Design, Proposed Design, Migration, Implementation Plan, and Decision Log. Then submit a PR from a bep/XXXX-short-title branch.

When should a BEP be split into multiple documents?▼

Segment a BEP when it exceeds roughly 500 lines, has 3 or more distinct components, has 3 or more independent implementation phases, or spans multiple subsystems. The main document stays under 200 lines as an overview and index, with detail files in a BEP-XXXX directory.

What is the context-for-ai block in a BEP?▼

The context-for-ai block is an HTML comment with key-value metadata added to the main document and each sub-document. It lets AI agents quickly understand scope, constraints, dependencies, and key decisions without parsing the full document.

What belongs in a BEP versus the implementation PR?▼

The BEP contains component responsibilities, observable contracts, design decisions with rationale, and the core cross-layer flow. The PR contains exact dataclass fields, function signatures, file anchors, and algorithm choices left to the implementer's discretion.

How do Decision Log and Open Questions work in a BEP?▼

Open Questions list unresolved items in the main document only. When a question is resolved, add a row with date, decision, and rationale to the Decision Log and remove it from Open Questions. Settled decisions should not be re-argued.

Related Skills

Explore More Software Engineering Skills→
OlatisunkanmiOlatisunkanmi
8

mine.research

Investigate proposed codebase changes and produce a validated research brief.

Community
Advanced
tldrawtldraw
50.1k

pr

Create or update GitHub pull requests for the current branch using gh CLI.

Official
Intermediate
colek42colek42
1

Critical Thinking & Self-Skepticism

Critique architecture and code by questioning assumptions and validating evidence.

Community
Basic
ChaiWithJaiChaiWithJai
1

technical-decision-record

Create Architecture Decision Records with standardized sections for context, constraints, options, decisions, and consequences.

Community
Intermediate