interview

Interview: Project Knowledge Collection

Collect project-specific knowledge through a structured 3-phase process. The output feeds into build-skills to create tailored review skills.

Step 0: Project Directory Setup (MUST do first)

The current directory IS the review data project. All files go directly here — do NOT create subdirectories like tailored-reviewer-data/ or review-data/.

Expected structure (all at current directory root):

./config.md
./knowledge-base/
./meta/
./workspace/          ← git clone of the target project
./.claude/skills/     ← generated by build-skills
./reviews/            ← review outputs
./backtest/           ← backtest cases and results
./CLAUDE.md           ← generated by this skill

If config.md already exists, this is an update. If not, this is a new project.

Prerequisites: The user should have created and cd'd into the project directory before running this skill (e.g., mkdir ~/review/rmw_zenoh && cd ~/review/rmw_zenoh).

Phase 1: Information Source Mapping

Map where project information lives. Ask the user one category at a time. Provide concrete examples to help them think of sources they might forget.

Questions to Ask

Ask these in order. For each, provide examples of what you're looking for:

1. Repository structure

   • "Is this a monorepo or multi-repo? What's the main repo URL?"
   • "Are there related repos (shared libraries, infrastructure, etc.)?"

2. Bug & task tracking

   • "Where do you track bugs? JIRA, GitHub Issues, ClickUp, Linear?"
   • "Is it one project per workspace or shared? What labels/filters identify bugs?"
   • "What bug tracking source should health-score use for bug occurrence trends?"

3. Error monitoring

   • "Do you use Sentry, Datadog, or similar? What's the project/service name?"
   • "Is there a separate staging vs production monitoring?"

4. Communication channels

   • "Which Slack/Teams channels are relevant? There's often more than one:"
   • " - General dev discussion"
   • " - Incident/alert channels"
   • " - Review request channels"
   • " - Deploy notification channels"

5. Documentation

   • "Where are specs? Design docs? Meeting notes? Postmortems?"
   • "These are often scattered — Confluence, Notion, Google Docs, repo wiki..."
   • "For each: what's the space/folder/URL pattern?"

6. Code quality tools

   • "SonarQube? ESLint/Prettier configs? Any custom linting?"

7. Roadmap & planning

   • "Where's the roadmap? Product specs? Sprint planning docs?"

8. Available Claude Code tools

   • "Which MCP servers do you have installed? (Slack MCP, Jira MCP, etc.)"
   • "This determines what I can read automatically in Phase 2."

9. Specification sources

   • "Where are feature specifications and design decisions recorded?"
   • " - Feature specs (Confluence, Notion, Google Docs, repo docs, etc.)"
   • " - Technical decisions (ADR, Slack channel, meeting notes, etc.)"
   • " - Does the location vary by area? (e.g., backend specs in Confluence, frontend in Figma)"
   • "For each: what's the space/folder/URL pattern to find them?"

10. Library / platform / API specification sources

    • "For well-known libraries (React, AWS SDK, etc.), we can find official docs ourselves — no need to list those."
    • "Are there internal libraries, company platforms, or niche external dependencies whose documentation lives somewhere specific?"
    • " - Internal shared libraries with their own docs"
    • " - Company platform APIs (internal API gateway, auth service, etc.)"
    • " - Less common external services with specific doc locations"
    • "If there's nothing like this, that's fine — just say so."

Output

Write results to:

• config.md — frontmatter (project_name, git_url, default_branch) + information source sections with full detail (see spec for format)
• knowledge-base/source-map.md — structured map of all identified sources with access methods

Phase 1.5: Development Branch Detection

Purpose: Some projects use a branch other than the GitHub default as their primary development branch (e.g., develop for active work, main only for releases). Using the wrong branch causes stale analysis.

Run immediately after Phase 1 (once git_url is known):

${CLAUDE_PLUGIN_ROOT}/scripts/detect-dev-branch.sh <owner/repo>

Interpreting Results

The script reports 3 signals. Use this decision logic:

1. If no candidate branches found → use GitHub default branch as-is
2. If a candidate branch has 2+ of these indicators, recommend it:
   • Receives majority (>50%) of merged PRs
   • Latest commit is >90 days newer than the default branch
   • Is significantly ahead (>10 commits) with 0 behind
3. Show findings to the user — always confirm before overriding the default:
   • "GitHub のデフォルトブランチは master ですが、実際の開発ブランチは develop のようです（最終コミット: 2026-03-09、masterより24コミット先行）。develop を主ブランチとして使ってよいですか？"

Storing the Result

Store the confirmed primary development branch as default_branch in config.md frontmatter. This is the branch that all tailored-reviewer operations (backtest, fact-check, workspace checkout) will use.

If the primary branch differs from the GitHub default, also note this in config.md body:

## Branch Strategy
- GitHub default branch: master (release branch, infrequently updated)
- Primary development branch: develop (stored as default_branch)

Phase 2: AI Self-Reading

Read from sources identified in Phase 1. Use only tools available in the user's Claude Code environment (MCP servers, gh CLI, git, file system). Do NOT attempt to access tools that aren't installed.

Reading Process

Execute these in order. For each, write results to the appropriate knowledge-base file with metadata frontmatter:

---
last_verified: YYYY-MM-DD
update_frequency: monthly | weekly
confidence: 0.0-1.0
sources:
  - "source description (date)"
---

1. Repository analysis → knowledge-base/project-context.md

   • Read README, CONTRIBUTING, architecture docs
   • Identify tech stack from package.json / requirements.txt / go.mod / etc.
   • Map directory structure and module boundaries

2. Design principles → knowledge-base/design-principles.md

   • Read any architecture/design documentation
   • If docs are missing or outdated (compare doc dates with code reality): infer from code patterns
   • Mark inferred principles with sources: ["コード推論: {path} のパターンから"]

3. Implementation principles → knowledge-base/implementation-principles.md

   • Read linting configs, CLAUDE.md, coding guidelines
   • Extract patterns from recent PRs (naming, error handling, testing style)

4. Bug patterns → knowledge-base/bug-patterns.md

   • Run: ${CLAUDE_PLUGIN_ROOT}/scripts/extract-fix-patterns.sh <workspace-path>
   • Analyze the output: which directories have most fixes? What types of bugs recur?

5. PR review patterns → knowledge-base/pr-review-patterns.md

   • Run: ${CLAUDE_PLUGIN_ROOT}/scripts/extract-pr-comments.sh <owner/repo>
   • Analyze: which reviewers comment most on which areas? What do they repeatedly flag?

6. Roadmap → knowledge-base/roadmap.md

   • Read roadmap docs if accessible via installed tools
   • If not accessible: mark confidence as low, flag for Phase 3

7. Team context → knowledge-base/team-context.md

   • Infer from git log (active contributors, areas of ownership)
   • Note: much of this requires user input in Phase 3

8. Spec sources → knowledge-base/spec-sources.md

   • Compile from Phase 1 questions 5, 9, and 10
   • Structure as a map: area/component → spec location + access method
   • Include internal library/platform doc locations if provided
   • If user said "nothing" for internal libs, note that (don't omit the file)
   • This file is used at review time by the orchestrator (Step 0.7) and by each perspective's Fact Check to look up specifications and API documentation

Staleness Detection

When reading documents, compare document dates with code reality:

• Design doc says "microservices architecture" but code is a monolith → flag as stale
• API doc lists endpoints that don't exist in code → flag as stale
• Flag stale sources in the metadata: confidence: 0.3, sources: ["STALE: doc.md (2024-01) vs code reality"]

Phase 3: Gap-Fill Questions

Review all knowledge-base files. For each:

• confidence < 0.8: Ask the user a specific, answerable question
  • Good: "I see src/payments/ has frequent fixes. Is there a known issue with the payment gateway integration?"
  • Bad: "Tell me about undocumented aspects of your project"
• confidence >= 0.8: Include in a final summary for bulk confirmation

Final Summary

Present a bulleted summary of everything collected, grouped by knowledge-base file. Ask the user to confirm or correct. Update files based on their response.

Update Mode

When run on a project that already has knowledge-base files:

1. Check last_verified + update_frequency on each file
2. Stale files → re-run the relevant Phase 2 step
3. Check for inconsistencies between per-review data and stored knowledge
4. Run Phase 3 only for items with decreased confidence

After Interview

1. If workspace/ doesn't exist: git clone <git_url> workspace/
2. Ensure workspace is on the correct branch: cd workspace && git checkout <default_branch from config.md> (this matters when the primary development branch differs from the GitHub default)
3. Create .gitignore if it doesn't exist (workspace/ should not be committed to the review data project):

   workspace/
   

4. Write meta/plugin-version-used.md with current tailored-reviewer version
5. Write meta/last-updated.md with current timestamps per file
6. Write CLAUDE.md at the project root with environment instructions:

# Review Data Project: {project_name}

This directory is a review data project for tailored-reviewer, NOT the project itself.

## Directory Structure
- `config.md` — project configuration
- `knowledge-base/` — collected project knowledge
- `meta/` — metadata (plugin-version, build-inputs, etc.)
- `workspace/` — git clone of {git_url}. This is the actual code.
- `.claude/skills/` — generated review skills
- `reviews/` — review output
- `backtest/` — backtest cases and results

## Important Rules
- All git/gh commands must run inside `workspace/`, not here
- `meta/` files go at this project root, NOT in `.claude/skills/meta/`
- Review outputs go to `reviews/`

7. Prompt user: "Knowledge base is ready. Run /build-skills to create project-specific review skills."