bugfix-319-setup-crash-on-repository-with-no-issues: Refactor agent documentation by moving use case flows to a dedicated file and enhancing Bugbot details with key paths and configuration.

efraespada · efraespada · commit 8fc06359d9e0 · 2026-02-27T21:42:42.000+01:00
diff --git a/README.md b/README.md
@@ -10,6 +10,8 @@
 
 Full documentation: **[docs.page/vypdev/copilot](https://docs.page/vypdev/copilot)**
 
+*Maintains state and configuration persisted in issue descriptions for seamless workflow automation.*
+
 ---
 
 ## Documentation index
diff --git a/_agent/docs/architecture.md b/_agent/docs/architecture.md
@@ -35,112 +35,3 @@ description: Project architecture, entry points, and use case flows.
 | Repos | `src/data/repository/` | branch_repository, issue_repository, workflow_repository, ai_repository (OpenCode), file_repository, project_repository |
 | Config | `src/utils/constants.ts` | INPUT_KEYS, ACTIONS, defaults |
 | Metadata | `action.yml` | Action inputs and defaults |
-
-## Schematic overview of use case flows
-
-Entry point: `mainRun(execution)` in `src/actions/common_action.ts`. After `execution.setup()` and optionally `waitForPreviousRuns`, the dispatch is:
-
-```
-mainRun
-├── runnedByToken && singleAction → SingleActionUseCase (only if validSingleAction)
-├── issueNumber === -1 → SingleActionUseCase (only if isSingleActionWithoutIssue) or skip
-├── welcome → log boxen and continue
-└── try:
-    ├── isSingleAction        → SingleActionUseCase
-    ├── isIssue                → issue.isIssueComment ? IssueCommentUseCase : IssueUseCase
-    ├── isPullRequest          → pullRequest.isPullRequestReviewComment ? PullRequestReviewCommentUseCase : PullRequestUseCase
-    ├── isPush                 → CommitUseCase
-    └── else                   → core.setFailed
-```
-
-### 1. IssueUseCase (`on: issues`, not a comment)
-
-**Step order:**
-
-1. **CheckPermissionsUseCase** → if it fails (not allowed): CloseNotAllowedIssueUseCase and return.
-2. **RemoveIssueBranchesUseCase** (only if `cleanIssueBranches`).
-3. **AssignMemberToIssueUseCase**
-4. **UpdateTitleUseCase**
-5. **UpdateIssueTypeUseCase**
-6. **LinkIssueProjectUseCase**
-7. **CheckPriorityIssueSizeUseCase**
-8. **PrepareBranchesUseCase** (if `isBranched`) **or** **RemoveIssueBranchesUseCase** (if not).
-9. **RemoveNotNeededBranchesUseCase**
-10. **DeployAddedUseCase** (deploy label)
-11. **DeployedAddedUseCase** (deployed label)
-12. If **issue.opened**:
-    - If not release and not question/help → **RecommendStepsUseCase**
-    - If question or help → **AnswerIssueHelpUseCase**
-
-### 2. IssueCommentUseCase (`on: issue_comment`)
-
-**Step order:**
-
-1. **CheckIssueCommentLanguageUseCase** (translation)
-2. **DetectBugbotFixIntentUseCase** → payload: `isFixRequest`, `isDoRequest`, `targetFindingIds`, `context`, `branchOverride`
-3. **ProjectRepository.isActorAllowedToModifyFiles(owner, actor, token)** (permission to modify files)
-4. Branch A – **if runAutofix && allowed**:
-   - **BugbotAutofixUseCase** → **runBugbotAutofixCommitAndPush** → if committed: **markFindingsResolved**
-5. Branch B – **if !runAutofix && canRunDoUserRequest && allowed**:
-   - **DoUserRequestUseCase** → **runUserRequestCommitAndPush**
-6. **If no file-modifying action ran** → **ThinkUseCase**
-
-### 3. PullRequestReviewCommentUseCase (`on: pull_request_review_comment`)
-
-Same flow as **IssueCommentUseCase**, with:
-
-- CheckIssueCommentLanguageUseCase → **CheckPullRequestCommentLanguageUseCase**
-- User comment: `param.pullRequest.commentBody`
-- DetectBugbotFixIntentUseCase may use **parent comment** (commentInReplyToId) in the prompt.
-
-### 4. PullRequestUseCase (`on: pull_request`, not a review comment)
-
-**Branches by PR state:**
-
-- **pullRequest.isOpened**:
-  1. UpdateTitleUseCase  
-  2. AssignMemberToIssueUseCase  
-  3. AssignReviewersToIssueUseCase  
-  4. LinkPullRequestProjectUseCase  
-  5. LinkPullRequestIssueUseCase  
-  6. SyncSizeAndProgressLabelsFromIssueToPrUseCase  
-  7. CheckPriorityPullRequestSizeUseCase  
-  8. If AI PR description: **UpdatePullRequestDescriptionUseCase**
-
-- **pullRequest.isSynchronize** (new pushes):
-  - If AI PR description: **UpdatePullRequestDescriptionUseCase**
-
-- **pullRequest.isClosed && isMerged**:
-  - **CloseIssueAfterMergingUseCase**
-
-### 5. CommitUseCase (`on: push`)
-
-**Precondition:** `param.commit.commits.length > 0` (if 0, return with no steps).
-
-**Order:**
-
-1. **NotifyNewCommitOnIssueUseCase**
-2. **CheckChangesIssueSizeUseCase**
-3. **CheckProgressUseCase** (OpenCode: progress + size labels on issue and PRs)
-4. **DetectPotentialProblemsUseCase** (Bugbot: detection, publish to issue/PR, resolved markers)
-
-### 6. SingleActionUseCase
-
-Invoked when:
-- `runnedByToken && isSingleAction && validSingleAction`, or
-- `issueNumber === -1 && isSingleAction && isSingleActionWithoutIssue`, or
-- `isSingleAction` in the main try block.
-
-**Dispatch by action (one per run):**
-
-| Action | Use case |
-|--------|----------|
-| `deployed_action` | DeployedActionUseCase |
-| `publish_github_action` | PublishGithubActionUseCase |
-| `create_release` | CreateReleaseUseCase |
-| `create_tag` | CreateTagUseCase |
-| `think_action` | ThinkUseCase |
-| `initial_setup` | InitialSetupUseCase |
-| `check_progress_action` | CheckProgressUseCase |
-| `detect_potential_problems_action` | DetectPotentialProblemsUseCase |
-| `recommend_steps_action` | RecommendStepsUseCase |
diff --git a/_agent/docs/bugbot.md b/_agent/docs/bugbot.md
@@ -1,12 +1,14 @@
 ---
 name: Bugbot
-description: Detailed technical reference for Bugbot (detection, markers, context, intent, autofix, do user request, permissions).
+description: Detailed technical reference for Bugbot (detection, markers, context, intent, autofix, do user request, permissions)
 ---
 
 # Bugbot – technical reference
 
 Bugbot has two main modes: **detection** (on push or single action) and **fix/do** (on issue comment or PR review comment). All Bugbot code lives under `src/usecase/steps/commit/bugbot/` and `src/usecase/steps/commit/` (DetectPotentialProblemsUseCase, user_request_use_case).
 
+---
+
 ## 1. Detection flow (push or single action)
 
 **Entry:** `CommitUseCase` (on push) calls `DetectPotentialProblemsUseCase`; or `SingleActionUseCase` when action is `detect_potential_problems_action`.
@@ -21,6 +23,19 @@ Bugbot has two main modes: **detection** (on push or single action) and **fix/do
 6. **Mark resolved:** `markFindingsResolved(execution, context, resolvedFindingIds, normalizedResolvedIds)` – for each existing finding in context whose id is in resolved set, update issue comment (and PR review comment if any) via `replaceMarkerInBody` to set `resolved:true`; if PR comment, call `resolveReviewThread` when applicable.
 7. **Publish:** `publishFindings(execution, context, toPublish, overflowCount?, overflowTitles?)` – for each finding: add or update **issue comment** (always); add or update **PR review comment** only when `finding.file` is in `prContext.prFiles` (using `pathToFirstDiffLine` when finding has no line). Each comment body is built with `buildCommentBody(finding, resolved)` and includes the **marker** `<!-- copilot-bugbot finding_id:"id" resolved:false -->`. Overflow: one extra issue comment summarizing excess findings.
 
+**Key paths (detection):**
+
+- `detect_potential_problems_use_case.ts` – orchestration
+- `load_bugbot_context_use_case.ts` – issue/PR comments, markers, previousFindingsBlock, prContext
+- `build_bugbot_prompt.ts` – prompt for plan agent (task 1: new findings, task 2: resolved ids)
+- `schema.ts` – BUGBOT_RESPONSE_SCHEMA (findings, resolved_finding_ids)
+- `marker.ts` – BUGBOT_MARKER_PREFIX, buildMarker, parseMarker, replaceMarkerInBody, extractTitleFromBody, buildCommentBody
+- `publish_findings_use_case.ts` – add/update issue comment, create/update PR review comment
+- `mark_findings_resolved_use_case.ts` – update comment body with resolved marker, resolve PR thread
+- `severity.ts`, `file_ignore.ts`, `path_validation.ts`, `limit_comments.ts`, `deduplicate_findings.ts`
+
+---
+
 ## 2. Marker format and context
 
 **Marker:** Hidden HTML comment in every finding comment (issue and PR):
@@ -31,6 +46,14 @@ Bugbot has two main modes: **detection** (on push or single action) and **fix/do
 - **Build:** `buildMarker(findingId, resolved)`. IDs are sanitized (`sanitizeFindingIdForMarker`) so they cannot break HTML (no `-->`, `<`, `>`, newlines, etc.).
 - **Update:** `replaceMarkerInBody(body, findingId, newResolved)` – used when marking a finding as resolved (same comment, body updated with `resolved:true`).
 
+**Context (`BugbotContext`):**
+
+- `existingByFindingId[id]`: `{ issueCommentId?, prCommentId?, prNumber?, resolved }` – from parsing all issue + PR comments for markers.
+- `issueComments`: raw list from API (for body when building previousFindingsBlock / unresolvedFindingsWithBody).
+- `openPrNumbers`, `previousFindingsBlock`, `prContext` (prHeadSha, prFiles, pathToFirstDiffLine), `unresolvedFindingsWithBody`: `{ id, fullBody }[]` for findings that are not resolved (body truncated to MAX_FINDING_BODY_LENGTH when loading).
+
+---
+
 ## 3. Fix intent and file-modifying actions (issue comment / PR review comment)
 
 **Entry:** `IssueCommentUseCase` or `PullRequestReviewCommentUseCase` (after language check).
@@ -62,3 +85,44 @@ Bugbot has two main modes: **detection** (on push or single action) and **fix/do
    - If success: `runUserRequestCommitAndPush(execution, { branchOverride })` – same verify/checkout/add/commit/push with message `chore(#N): apply user request` or `chore: apply user request`.
 
 5. **Think** (when no file-modifying action ran): `ThinkUseCase.invoke(param)` – answers the user (e.g. question).
+
+**Key paths (fix/do):**
+
+- `detect_bugbot_fix_intent_use_case.ts` – intent detection, branch resolution for issue_comment
+- `build_bugbot_fix_intent_prompt.ts` – prompt for is_fix_request / is_do_request / target_finding_ids
+- `bugbot_fix_intent_payload.ts` – getBugbotFixIntentPayload, canRunBugbotAutofix, canRunDoUserRequest
+- `schema.ts` – BUGBOT_FIX_INTENT_RESPONSE_SCHEMA (is_fix_request, target_finding_ids, is_do_request)
+- `bugbot_autofix_use_case.ts` – build prompt, copilotMessage (build agent)
+- `build_bugbot_fix_prompt.ts` – fix prompt (findings block, verify commands, truncate finding body to MAX_FINDING_BODY_LENGTH)
+- `bugbot_autofix_commit.ts` – runBugbotAutofixCommitAndPush, runUserRequestCommitAndPush (checkout, verify commands max 20, git config, add, commit, push)
+- `user_request_use_case.ts` – DoUserRequestUseCase, buildUserRequestPrompt
+- `mark_findings_resolved_use_case.ts` – update issue/PR comment with resolved marker
+- `project_repository.ts` – isActorAllowedToModifyFiles
+
+---
+
+## 4. Configuration (inputs / Ai model)
+
+- **bugbot-severity:** Minimum severity to publish (info, low, medium, high). Default low. `getBugbotMinSeverity()`, `normalizeMinSeverity`, `meetsMinSeverity`.
+- **bugbot-comment-limit:** Max individual finding comments per issue/PR (overflow gets one summary). Default 20. `getBugbotCommentLimit()`, `applyCommentLimit`.
+- **bugbot-fix-verify-commands:** Comma-separated commands run after autofix (and do user request) before commit. `getBugbotFixVerifyCommands()`, parsed with shell-quote; max 20 executed. Stored in `Ai` model; read in `github_action.ts` / `local_action.ts`.
+- **ai-ignore-files:** Exclude paths from detection (and from reporting). Used in buildBugbotPrompt and in filtering findings.
+
+---
+
+## 5. Constants and types
+
+- `BUGBOT_MARKER_PREFIX`: `'copilot-bugbot'`
+- `BUGBOT_MAX_COMMENTS`: 20 (default limit)
+- `MAX_FINDING_BODY_LENGTH`: 12000 (truncation when loading context and in build_bugbot_fix_prompt)
+- `MAX_VERIFY_COMMANDS`: 20 (in bugbot_autofix_commit)
+- Types: `BugbotContext`, `BugbotFinding` (id, title, description, file?, line?, severity?, suggestion?), `UnresolvedFindingSummary`, `BugbotFixIntentPayload`.
+
+---
+
+## 6. Sanitization and safety
+
+- **User comment in prompts:** `sanitizeUserCommentForPrompt(raw)` – trim, escape backslashes, replace `"""`, truncate 4000 with no lone trailing backslash.
+- **Finding body in prompts:** `truncateFindingBody(body, MAX_FINDING_BODY_LENGTH)` with suffix `[... truncated for length ...]` (used in load_bugbot_context and build_bugbot_fix_prompt).
+- **Verify commands:** Parsed with shell-quote; no shell operators (;, |, etc.); max 20 run.
+- **Path:** `isSafeFindingFilePath` (no null byte, no `..`, no absolute); PR review comment only if file in `prFiles`.
diff --git a/_agent/docs/code-conventions.md b/_agent/docs/code-conventions.md
@@ -1,6 +1,6 @@
 ---
-name: CodeConventions
-description: Coding standards, logging, and adding new inputs.
+name: Code Conventions
+description: Copilot – coding conventions and where to change things
 ---
 
 # Code Conventions
diff --git a/_agent/docs/commit-messages.md b/_agent/docs/commit-messages.md
@@ -1,6 +1,6 @@
 ---
-name: CommitMessages
-description: Specific nomenclature and branch-prefix requirements for commits.
+name: Commit Messages
+description: Commit message nomenclature (prefix = current branch)
 ---
 
 # Commit messages
diff --git a/_agent/docs/project-context.md b/_agent/docs/project-context.md
@@ -1,6 +1,6 @@
 ---
-name: ProjectContext
-description: High-level overview, common commands, and ignore paths.
+name: Project Context
+description: Copilot – quick read, commands, and where to find more
 ---
 
 # Copilot – Project Context
@@ -33,3 +33,8 @@ npm run lint:fix
 
 - **`build/`** – Generated output; do not edit or run tests/lint against it.
 - **`.agent-sessions/`** – Session data; ignore unless debugging.
+
+## Other rules
+
+- **Architecture & paths**: see `architecture.md` (entry points, use cases, single actions, key files).
+- **Code conventions**: see `code-conventions.md` (logger, constants, adding inputs, ncc).
diff --git a/_agent/docs/usecase-flows.md b/_agent/docs/usecase-flows.md
diff --git a/docs/configuration.mdx b/docs/configuration.mdx
