# Office Hours > Use when running an attended dev-loop office-hours checkpoint before prep, promotion, or /goal to choose one current-project or cross-project topic and capture requirements. - Skill: `karlorz/office-hours` (Agent Skill) - Install (CLI): `npx skillmds@latest add karlorz/office-hours` - Raw SKILL.md: https://api.skillmd.com/api/skills/karlorz/office-hours/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: karlorz (https://skillmd.com/u/karlorz) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/karlorz/office-hours --- # Dev-Loop Office Hours Attended requirements intake for **one** selected project topic. Runs before `/dev-loop prep`, promotion to planned work, or `/goal`: refreshes selected project brain context unattended, lists current-project or requested cross-project candidates, asks concrete requirement questions one at a time, writes a vault-native report, and stops with a recommended next action. Office-hours is not `/dev-loop prep`. Prep approves automation readiness for known work; office-hours helps decide what one thing needs clearer requirements before prep or execution. ## Hard Rules 1. Run in the `main session only`. Do NOT spawn subagents for intake, candidate selection, or approval. `Do NOT call structured question tools from subagents`. 2. Handle exactly one topic, capture, or work item per ordinary invocation. Ranked-audit reconciliation treats one audit report as the selected topic and may resolve multiple candidate verdicts inside that report. 3. Brain and memory refresh is fully unattended — never ask the user to choose memory pages, wiki layers, or project-index refresh strategy. 4. Do NOT auto-select a no-topic candidate. List current-project candidates, or requested cross-project candidates, first; then ask the user which project, candidate, or free-text topic to focus on. 5. `Do NOT modify raw transcripts` (immutable in v1). 6. `Do NOT auto-create planned work`. 7. `Do NOT set preflight readiness` fields (`automation_ready`, `human_questions_resolved`, `spec_preflight_approved`, `plan_preflight_approved`, `preflight_state`, `last_preflight`). 8. `Do NOT start or manage `/goal``. 9. Always write a report when the session reaches a selected topic, even if the decision is defer or research more. ## First-Run Anchoring Prevent a fresh topic from anchoring to stale or completed work. Apply during candidate selection and topic confirmation. - A fresh user-supplied free-text topic is a valid selected topic after refresh. Do not force the user to pick an inventory candidate; list related candidates as context only. - Completed or abandoned work items are **evidence**, not active candidates. Surface them only for context unless the user explicitly asks to reopen one. - If the invocation names a `completed` or `abandoned` work item, state that it is completed and ask whether to reopen it or treat it as evidence before proceeding. Do not silently resume completed work. - Reports must label fresh follow-up topics versus resumed work items (Report). ## Non-Interactive Guard Office-hours is attended. Before prompting, detect non-interactive context: an active `/goal` evaluator or unattended orchestrator; `codex exec`, CI, cron, scheduled satellite, or no TTY-style channel; or a subagent/nested-worker. If non-interactive, do not ask questions or write decisions — emit: ```text Office-hours requires an attended main session. Run it before /goal or prep. ``` If the user supplied a topic, you may still perform read-only brain refresh and print candidate context, but stop before any prompt or write. ## Inputs ```text /dev-loop office-hours /dev-loop office-hours --all /dev-loop office-hours --all-projects /dev-loop office-hours /dev-loop office-hours /dev-loop office-hours raw/transcripts/.md /dev-loop office-hours --reconcile ``` `--all` (or a "show all" request) expands the candidate list from the default bounded batch to full current-project scope. Keep the workflow one-topic after the user selects a candidate. `--all-projects`, "all projects", "choose project", or "list current project slugs" starts in cross-project discovery mode. It lists candidates from every `projects//work/` directory and lets the user choose a project or exact candidate. Keep the workflow one-topic after selection. The report and any managed backreference still belong to the selected project's ``, not to a global location. ## Ranked Audit Reconciliation Mode Enter this mode only when `--reconcile` and one exact ranked-audit report path are present. The report is the selected topic; do not run ordinary candidate selection. 1. Require an attended main session. In `/goal`, CI, cron, satellite, nested worker, or other non-interactive context, stop with: `Ranked-audit reconciliation requires an attended main session.` 2. Re-read the audit report and every referenced work-item spec. Compare current hashes with the report evidence; stale targets require a rescan or explicit read-only continuation. 3. Treat `active-code-work` as no-change context unless newer evidence conflicts. 4. For `delivered-close-candidate`, `verification-only`, `stale-or-superseded`, `human-gated`, and `unverifiable`, ask one verdict question at a time. Put an evidence-backed recommendation first. 5. Accumulate proposed actions: close delivered scope, convert optional verification to post-release prose, update progress, defer, abandon, leave unchanged, or research more. 6. Do not mutate any work item before final batch approval. Show one exact diff-style summary of files, lifecycle fields, checklist changes, and index or log projections. Ask for final batch approval through the main-session question runner. 7. If approval is declined, write the reconciliation decision report only. 8. If approved, apply the minimal project-work edits, then run `skillwiki validate` and `skillwiki work-validate` for every target. Use `--require-complete` for each closure. Refresh affected project indexes and append managed lifecycle log events; never hand-edit root `index.md` or `log.md`. 9. Draft the cross-project reconciliation report outside the vault and publish it through `skillwiki page publish` at: `meta/YYYY-MM-DD-ranked-audit-reconciliation.md`. Link the source ranked-audit report, record every asked question and answer, list approved and declined mutations, and report validation results. 10. Stop after the reconciliation report. Do not enter the ordinary Refresh, candidate-selection, requirement-question, project requirements-report, or backreference flow below. Apply SkillWiki's work-item completion contract during reconciliation: required acceptance checks may block closure; typed opt-in post-release verification does not and must not remain as unchecked completion tasks. Treat the schema's `post_release_verification.triggers` values as the authoritative resurfacing conditions. ## Refresh Resolve the same project context dev-loop uses: 1. Read `.claude/dev-loop.config.md` if present. 2. Resolve default `` from config; fall back to the repo basename. 3. Resolve `` from the configured SkillWiki backend. If `auto` or absent, run `skillwiki path`; if that fails, use a validated `~/wiki` only when `~/wiki/SCHEMA.md` and `~/wiki/projects/` exist. 4. Resolve `` as the current working repository for current-project discovery only. Cross-project discovery must not borrow `` repo evidence for other projects. 5. Resolve the skill directory so helper calls run relative to this skill root. The default `` is only the starting scope. If the invocation asks for all projects, project choice, or the resolved default slug is not a valid `projects//` directory, enter cross-project discovery mode instead of failing on the default slug. If no SkillWiki vault resolves, refuse v1 office-hours: ```text Office-hours v1 requires a SkillWiki vault so it can list project work and write a requirements report. ``` ### Project Repository Metadata Cross-project repo evidence is local-only and host-aware. The durable metadata home is: ```text projects/llm-wiki/architecture/project-repos.yaml ``` If that coordinator file is absent, fall back to `projects//architecture/project-repos.yaml` for the selected project. The minimal schema is host plus user scoped: ```yaml schema_version: 1 coordinator_project: llm-wiki hosts: macos-dev: users: karlchow: workspace_roots: - ~/Desktop/code sg01: users: root: workspace_roots: - ~/projects projects: agent-skills: repo_names: - agent-skills remote_urls: - git@github.com:karlorz/agent-skills.git - https://github.com/karlorz/agent-skills.git llm-wiki: host_overrides: sg02: users: agent-memory: repo_path: /home/agent-memory/llm-wiki ``` If `repo_names` is absent, use the project slug as the repo directory fallback. Expand `~` for the runtime user. Accept only paths that are git repositories. When `remote_urls` is configured, require a matching local git remote before trusting repo-derived evidence. Office-hours v1 does not SSH to remote hosts to inspect repositories. Missing local checkouts degrade explicitly. Treat resolver statuses as follows: - `resolved` — include repo-derived evidence for the selected project. - `unresolved` — continue intake, but label repo evidence unavailable. - `ambiguous` — continue intake only after saying multiple local matches exist; recommend a per-host/user `repo_path` override. - `wrong_remote` — continue intake, but do not trust the checkout because the configured remote does not match. - `host_unknown` — continue intake, but say the current host/user is not configured in `project-repos.yaml`. ### Discovery Scope Use current-project discovery unless the invocation explicitly asks for cross-project/project selection or the default slug is invalid. **Current-project discovery.** Run the normal brain refresh for ``, then run the inventory helper for that one project. **Cross-project discovery.** Do not run memory refresh or project-index for every project upfront. First run the inventory helper across projects: ```bash # Prefer work-lane first for fast chooser (skip capture walk + repo evidence) node scripts/preflight-inventory.js \ --all-projects --vault --limit --lane work ``` With `--all` or a "show all projects/work" request, add `--all`. Only add `--lane captures` (and later hygiene) after the user narrows to projects that need unclaimed transcripts — avoid default all-lane global scans on large vaults. Cross-project discovery is vault-only. Do not pass the current repository as evidence for every project; if a legacy caller passes `--repo`, the helper must ignore repo evidence while `--all-projects` is active. ### Inventory performance / degradation The helper used to hang on large vaults when office-hours requested global or all-lane discovery. Root causes (fixed in the helper, still matter for usage): - Work trees with 100+ **completed** items previously ran `skillwiki validate` on every item; completed items are now skipped without validation. - `--lane work` previously still walked `raw/transcripts/` and ran implemented-capture / dirty-critical-path logic; lane flags now short-circuit those scans. - `--all-projects` previously re-read every transcript once per project; capture scans now partition in one vault pass. - Repo evidence still indexes local checkouts — prefer vault-only discovery until a single project is selected. **If the helper is still too slow or hangs:** 1. Kill stuck `preflight-inventory.js` processes rather than stacking retries. 2. Fall back to a **hand inventory**: list finance-related (or domain-related) `projects/*/work` open statuses and, if needed, `raw/transcripts` task/bug captures for those slugs only. 3. Present the hand list as the chooser (do not auto-select). 4. After the user picks **one** topic, run brain refresh + **project-scoped** inventory only: ```bash node scripts/preflight-inventory.js \ --project --vault --limit 15 --lane work # add --lane captures only if the topic is a capture; avoid --all on huge work trees ``` 5. Document the degradation in the report `## Context` when used. Present a compact project chooser from the helper's `projects[]` summaries and the candidate list grouped by `project_slug`, then lane. Include enough detail for each candidate to distinguish project, lane, status, priority, path, and findings. Ask the user to choose one project slug, one exact candidate, or a fresh free-text topic. If the user chooses only a project slug, rerun current-project discovery for that slug and ask for one candidate or free-text topic inside that project. Once a project or candidate is selected, set `` to the selected `project_slug`, resolve the selected project repository using `project-repos.yaml`, and run the normal brain refresh for that one project before requirement questions. If the repository resolves, rerun project-scoped inventory with the resolved repo path or the project-repos resolver enabled. If it does not resolve, rerun or continue project-scoped inventory with repo evidence disabled and show the degraded resolver status. Do not write a cross-project report. ### Brain Refresh Run read-mostly, without asking the user to choose: ```bash skillwiki memory index --project skillwiki memory topics --project --limit skillwiki project-index ``` Treat `skillwiki project-index ` as an orientation/staleness read only — never turn it into readiness approval. Summarize compactly: memory index (refreshed/already fresh/missing/failed), memory topics (top themes, recency), project index (fresh/stale/missing/failed), and any limiting failures. Report memory failures and continue; do not ask the user how to handle them. ### Candidate Inventory Run the deterministic preflight inventory helper from the dev-loop skill directory: ```bash node scripts/preflight-inventory.js \ --project --vault --repo --limit ``` For a cross-project selection, rerun the selected project inventory with the coordinator metadata so the helper can resolve the selected project repository: ```bash node scripts/preflight-inventory.js \ --project --vault --project-repos --limit ``` Default `` from `preflight.default_limit` when configured, otherwise `5`. With `--all` or a "show all" request, rerun with `--all`. Present candidates grouped by helper lane: `work` (planned, in-progress, or repairable work items), `captures` (unclaimed project raw transcript tasks or bugs), `hygiene` (structural issues needing human attention). In cross-project discovery, group first by `project_slug`, then by lane. Keep selected-topic intake project-scoped — do not list global wiki items unless linked to the selected project. If there are no candidates, present the brain refresh topics for the selected project and ask for one free-text focus topic. ## Select One Topic Apply the First-Run Anchoring rules here. - If the invocation names a work item, raw transcript, or topic: first check whether a named work item is `completed` or `abandoned` — if so, apply the completed-as-evidence rule (ask reopen-vs-evidence) before doing anything else. Otherwise treat it as the selected topic after refresh and surface related candidates for context. - If no topic is supplied, ask the user to pick one candidate or provide a free-text topic. In cross-project discovery, allow the first decision to be a project slug; then rerun the selected project's normal inventory and ask for one candidate or topic. - Never choose the top candidate automatically. - Re-read the selected source immediately before asking requirement questions. - If the source changed since inventory, state it is stale and ask whether to continue read-only or rerun inventory. - If the selected source is a raw `task` or `bug` capture, re-run the helper read-only over the selected project candidates and check whether that capture now appears in `hygiene` with `possibly_implemented_without_closure`. When it does, present the helper's evidence (`implemented_evidence` terms, `git_matches`, and relevant files) before normal intake. Ask the user to choose the handling path: `discard`, `merge-existing`, `hygiene-cleanup`, `research-more`, or continue normal requirements intake. Do not archive, edit raw transcripts, add `closes:`, or mark the capture complete from this heuristic alone. Use a structured question for candidate choice when available (it is a decision point). Put the recommended candidate first only with an evidence-based recommendation; otherwise list in inventory order. ## Question Runner Use structured question tools for decision points: | Platform | Structured question tool | |---|---| | Claude Code | `AskUserQuestion` | | Codex CLI or Codex App | `request_user_input` in Codex Plan mode; numbered conversational fallback in Codex Default mode | | Antigravity CLI | `ask_question` | | None available | `conversational fallback` | Probe the live tool surface before calling a structured question tool. In Codex App/CLI, use `request_user_input` only in Plan mode when the tool is exposed. In Codex Default mode, do not call it; use conversational fallback with numbered choices and wait for a normal user reply. Decision points: choose one project in cross-project discovery; choose one focus candidate; continue read-only after stale inventory or rerun; choose the final decision; confirm a managed `## Office Hours` section update on a work-item spec. Use conversational free text for nuanced requirements. Ask one question at a time, then decide the next. Stop once the next action is clear — prefer 2-5 good questions over a long checklist. All questions must be in the main session only. ## Infer Intake Mode Infer an internal mode from the selected source. Do not present `product | builder | maintenance` as the primary user picker. | Mode | Signals | Question focus | |---|---|---| | `product` | User-facing behavior, UX, customer value | User, outcome, scope, acceptance | | `builder` | Implementation plan, API, tests, architecture, developer workflow | Behavior delta, constraints, files, compatibility, verification | | `maintenance` | Hygiene, stale work, broken schema, failed validation, cleanup | Symptom, invariant, risk, rollback, validation | If confidence is low, ask: "What decision should this office-hours session unlock: product scope, implementation direction, or maintenance triage?" Record the inferred mode and confidence in the report. ## Requirement Questions Ask only enough to remove the next-action blocker. **Product.** 1. Who is affected, and what should be different after this ships? 2. What is explicitly out of scope for v1? 3. What acceptance signal proves this is done? 4. What risk would make you defer or split the work? **Builder.** 1. What behavior or interface should change? 2. Which existing files, conventions, or compatibility constraints must be respected? 3. What validation is enough (tests, manual smoke, docs, release check, another command)? 4. Is there a simpler path that preserves the required behavior? **Maintenance.** 1. What symptom or stale state should disappear? 2. What must remain unchanged? 3. What is the safe rollback or no-op boundary? 4. Which command or vault validation proves the cleanup is safe? If an answer reveals multiple topics, choose one with the user and record the rest under remaining uncertainty. ## Decision End with one recommended next action and the user's decision. Do not execute it automatically — office-hours stops after the report. - `promote-to-prep` — run `/dev-loop prep` for this now-clear work. - `direct-dev-loop` — scope is clear enough for a single attended or normal dev-loop cycle, without readiness approval. - `research-more` — evidence insufficient; use investigate or deep research. - `merge-existing` — link to an existing work item instead of creating another. - `hygiene-cleanup` — likely implemented but unclosed; create or update only a managed follow-up/report so a human can add an explicit closure or archive later. - `defer` — keep the report as context, no immediate work. - `discard` — no action. ## Report Always write the report after a topic is selected: ```text projects//requirements/YYYY-MM-DD-office-hours-.md ``` Use the local date and a filesystem-safe `` slug; if the path exists, append `-2`, `-3`, etc. Recommended frontmatter: ```yaml --- title: "Dev Loop Office Hours - " project: "[[]]" created: YYYY-MM-DD updated: YYYY-MM-DD kind: decision status: completed --- ``` Required sections: `# Dev Loop Office Hours - `, `## Context`, `## Brain Refresh Summary`, `## Inferred Intake Mode`, `## Questions And Answers`, `## Decision`, `## Recommended Next Action`, `## Links`. The body records: selected candidate and lane (if any); source path and hash (if available); inferred mode and confidence; asked questions; recommended defaults; user answers; remaining uncertainty; decision; recommended next action; stale-actionability recheck evidence when applicable; links to related work items, raw transcripts, query pages, or concepts. If cross-project discovery was used, record the selected `project_slug`, whether the user chose a project first or an exact candidate, and any nearby cross-project alternatives that were intentionally left out of scope. Also record the selected project's repo resolution status, resolved repo path when available, and whether repo-derived evidence was included. **Fresh-vs-resumed labelling:** in `## Context`, explicitly state whether this is a fresh follow-up topic or a resumed work item. If a completed/abandoned item was treated as evidence, record that and note it was not reopened. Keep this report distinct from `/dev-loop prep` reports. Do not put readiness approval language in the report unless the user is explicitly told that office-hours does not set readiness fields. ## Backreferences If the selected source is a work item, ask whether to add or update a managed section in that work item's `spec.md`: ```markdown ## Office Hours - Date: YYYY-MM-DD - Report: projects//requirements/YYYY-MM-DD-office-hours-.md - Decision: - Recommended next action: ``` Only edit this managed `## Office Hours` section; preserve all other content. After editing, run `skillwiki validate `. If validation fails, repair only the managed section when obvious; otherwise revert it and report the blocker. If the selected source is a raw transcript, do NOT modify raw transcripts. Link it from the report and recommend the explicit promotion, research, merge, defer, or discard action. ## Relationship To Other Skills `grill-me` is an optional future escalation hook, not a v1 dependency. If the conversation becomes too broad or adversarial clarification would help, record that the next session should invoke `grill-me` for the selected topic. Do not invoke `grill-me` automatically from office-hours v1.