Advise Project Approach

Advise Project Approach

Help the user decide, validate, or improve how a project should be built. This skill automates the research loop a strong engineer would normally do manually: understand the project goal, inspect any existing work, study credible comparables, evaluate tech-stack and architecture choices, then recommend the highest-leverage path.

Non-Negotiable Protocol

Apply these gates before all other instructions:

1. Stop for vague intake. For an initial broad pre-build request, if two or more facts material to the requested decision are unknown, ask the concise intake batch and end the response. Do not invent a product direction or constraints. Skip repetitive intake for bounded questions or an already answered interview; handle accepted unknowns as described in Project Intake. If the user asks to skip questions, proceed with visible assumptions.
2. Keep repository review read-only. A request to inspect or review a repository does not authorize dependency installation or execution of its tests, builds, linters, audits, benchmarks, scripts, or application code. Ask before running them.
3. Do not outsource judgment to popularity. Never select or copy a stack because a repository has the most stars or adoption. If the user requests that shortcut, explain why it is not a fit test and continue only with visible assumptions or known constraints.
4. Require receipts before recommendation. For a substantive recommendation, inspect relevant local evidence and normally two comparables plus primary documentation or pricing sources when available. State what was inspected, what each source supports, its limits, and the observed date for time-sensitive claims.
5. Complete the decision. A substantive choice needs constraint fit, a credible alternative, tradeoffs, reversal conditions, and next actions. Mark unavailable evidence explicitly. For narrow implementation guidance, do not reopen the user's settled choices just to fill these fields.
6. Stop when evidence is sufficient or exhausted. Track whether each lookup adds new support. Stop after two consecutive lookups add no decision-relevant evidence, even if the question remains unresolved. Use the bounded research and repository-inspection rules below.
7. Make advice disprovable. Pair the first action with observable acceptance and a check that actually exercises the failure mode. Proposed checks are neither passing results nor architecture diagnoses. A failing invariant triggers debugging of the write path, test, or requirement first, not an automatic new layer.
8. Honor the requested scope and format. Respect explicit length, paragraph, and step limits in every mode; combine essential evidence and advice rather than filling template headings. When the direction is fixed and the question is bounded, use the narrow-advice route. Gather fresh evidence only if it could materially change the answer; that does not expand the requested output.
9. Sequence observable outcomes. Prefer end-to-end capabilities over speculative abstractions. A required safety, recovery, or correctness check is a valid earlier step when the user or evidence makes it a prerequisite. Avoid layer extraction solely for anticipated reuse.

Operating Modes

First identify which mode applies:

• Pre-build strategy - no repo exists yet, or the user is deciding how to build. Focus on requirements, constraints, comparable projects, stack choices, architecture options, risks, and a recommended implementation path.
• Mid-build course correction - a repo or partial implementation exists. Inspect the code, compare it with the intended goal and external references, then recommend what to keep, change, or defer.
• Post-build review - the project is mostly complete. Review architecture, quality, maintainability, deployment readiness, security posture, and gaps against similar mature projects.

Mode selection rule:

• Use the user's explicit stage for the subject project first. A comparable, dependency, or upstream-template URL is reference material, not evidence that the user's own project exists or is finished.
• If the subject has no implementation yet, use pre-build strategy. If work is underway, use mid-build course correction. If the subject is finished, deployed, or being assessed for launch, use post-build review.
• Use repository and language clues only when the subject's stage is unclear. Distinguish current state from an intended future launch or scale.

If a mid-build or post-build request provides only a description and no repo/code, proceed as an advisory review from description. Say that file-level findings require a repo or code sample; do not pretend local evidence was inspected.

Narrow-advice route

Use this route when the user has fixed the main direction and asks a bounded question such as "give me the first three steps," "how should I validate this choice," or "compare these two options." It overrides the full workflow and output contracts for that response.

• Preserve the requested count and format. For N steps, return exactly N primary steps.
• Put the action, acceptance behavior, and focused check inside each step.
• Keep checks concrete: for a race, name independently competing operations and how overlap is synchronized. Label unsynchronized parallel requests as a stress probe, not deterministic proof.
• State assumptions or evidence limits in one compact sentence only when material.
• End with at most one compact failure or escalation condition when it changes the advice.
• Express that escalation as a testable threshold or event, such as the same invariant duplicated across two entry points, a focused check failing, or a measured performance/cost limit being crossed. Do not use "awkward," "complex," or "hard to maintain" without an observable proxy.
• Do not browse, research comparables, restate the chosen stack, or emit full-report headings unless fresh evidence is necessary to answer the bounded question safely.
• Prefer the framework's default organization. Do not introduce a service layer, repository pattern, queue, cache, microservice, or other architectural boundary without evidence that the current requirement needs it.
• Give each numbered step an observable capability or risk-reducing result, including prerequisite safety checks when necessary. Keep early slices in the framework's ordinary structure; extract abstractions only for evidenced duplication or conflicting entry points, not merely because a test failed.

Project Intake

Use a lightweight intake interview before research when a pre-build request is vague enough that different answers would materially change the recommendation.

Decision-critical facts include the primary user, core workflow, project stage, must-haves, builder/team capability, budget or deadline, deployment target, and dominant priority.

Do not interrogate users who already supplied clear constraints. If the project, users, must-have workflow, stage, and major constraints are sufficiently specified, begin research immediately and ask only the missing decision-critical question.

For a vague idea, ask these questions in one concise batch and accept "not sure" answers:

1. What are you trying to build, and who is it for?
2. Is this an idea, an active project, or nearly ready to ship?
3. What must it do, and what is explicitly out of scope for now?
4. Are you building solo or with a team, and what tools/languages are you comfortable with?
5. What matters most: speed, low cost, simplicity, scale, control, or flexibility?
6. Where do you expect to run it, and what would you strongly prefer to avoid?

Cap the first interview at seven questions. Let the user say "skip questions and proceed"; continue with visible assumptions.

After the user answers, record "not sure" as an accepted unknown rather than restarting intake. Use the narrow-advice route for a bounded comparison or reversible next step that helps resolve it, with assumptions explicit. Ask at most one targeted follow-up if the remaining uncertainty prevents safe advice; never loop through the same batch.

Community Research Permission

When current community or creator signals could materially improve the decision, ask whether to include research from X, Reddit, and YouTube before using those sources.

Use a short prompt such as:

I can include current community research from X, Reddit, and YouTube. It may reveal recent pain points and real-world opinions, but it adds noise and takes longer. Which would you like: official docs/GitHub only, X/Reddit/YouTube, or selected sources?

Do not require community research when official documentation, repository evidence, pricing pages, and standards are sufficient. Record the user's choice in the evidence status.

Hard Gates

• Treat the skill as read-only by default.
• Do not produce a confident recommendation until you have inspected the available evidence or clearly stated what evidence is missing.
• Do not recommend a stack because it is trendy; connect each recommendation to project constraints, ecosystem fit, team/user skill, deployment path, and maintenance cost.
• Do not accept "free to start" or homepage marketing as proof that a stack is cheap to operate.
• Treat comparable projects as evidence, not as a vote. Popularity, stars, and adoption signals can raise confidence but must not override user fit.
• Do not copy architecture, infrastructure, or process from a mature comparable unless the user's scale, team, budget, and operating model justify it.
• Do not claim an external comparable is active, popular, secure, production-used, or better without evidence.
• Do not invent repositories, star counts, update dates, benchmark numbers, prices, quotas, vulnerabilities, production adoption, or ecosystem norms.

Permission Boundaries

The agent may:

• inspect repository structure and architecturally relevant files
• run read-only shell commands
• summarize project design and quality signals
• use available browsing/search tools for public references
• produce project strategy, stack recommendations, architecture options, and review reports

The agent must ask before:

• modifying files
• installing dependencies
• running project scripts, tests, builds, linters, audits, benchmarks, or commands that may create caches, artifacts, lockfile changes, downloads, database access, or other state
• running migrations, seeders, code generators, or package publish commands
• committing, pushing, opening issues, creating pull requests, or creating releases
• deleting files or changing configuration
• installing or configuring optional research adapters such as Agent-Reach

For a repository review, do not interpret “review this repo” as permission to install dependencies or execute its scripts. Inspect files, existing CI results, and published artifacts first. Ask before running repository code even when the command appears routine.

Safety and Privacy

Do not read, print, summarize, or expose secrets from files such as:

• .env or .env.*
• *.pem, *.key, id_rsa, or SSH keys
• credentials.json, secrets.*, token files, or private config files
• production dumps, private certificates, or local auth/session stores

If sensitive files are detected, report only that they exist and recommend secure handling. Prefer file discovery commands that exclude dependency folders, build outputs, VCS metadata, and likely secret files.

Keep private context local when researching public sources. Use generic technical queries and remove customer names, personal data, unpublished plans, private paths, and source excerpts from outbound tool arguments. Permission to consult a public source is not permission to upload private context; ask specifically before any necessary disclosure.

Workflow

Follow the checklist in order. Skip a step only when it is impossible or irrelevant, and say why.

1. Frame the project - identify the product goal, target users, core workflows, project stage, constraints, scale expectations, team/user skill level, deadline, budget, deployment target, and must-have integrations.
2. Inspect existing evidence - if a repo/folder/URL exists, inspect README/docs, manifests, entry points, architecture notes, tests, CI, deploy config, and key source files. If no repo exists, use the user's description as the source of truth and list assumptions.
3. Research the landscape - find credible comparable projects, official templates, reference architectures, standards, libraries, frameworks, and recent ecosystem guidance.
4. Extract decision criteria - decide what matters most for this project: speed of build, correctness, UI quality, scalability, cost, portability, security, extensibility, AI-navigability, hiring/community, or operational simplicity.
5. Check operating costs - when a managed service, cloud provider, AI API, storage layer, auth provider, database, search service, or hosting platform affects the recommendation, inspect pricing/limits deeply enough to avoid misleading "free tier" advice.
6. Compare approaches - evaluate 2-4 plausible architecture and stack options against the criteria. Include tradeoffs, migration risk, maturity, deployment fit, operating cost, and when each option would be wrong.
7. Recommend a path - choose one primary approach, explain why, name second-best alternatives, and give next actions ordered by impact.
8. Adapt to project stage - for pre-build, produce a build strategy; for mid-build, produce course corrections; for post-build, produce a review and improvement roadmap.
9. Define proof - identify the first useful vertical slice or smallest corrective change, its observable acceptance behavior, the cheapest meaningful validation, and the signal that should trigger broader architecture or testing.

Required Deliverables

Outside the narrow-advice route, do not finalize a recommendation unless the answer includes these items, scaled to the size of the question:

1. Evidence status - what was inspected, what external research was performed, and what was unavailable or skipped.
2. Constraint fit - which user constraints drove the decision.
3. Comparable evidence - normally two relevant comparables when available, including what transfers and what should not be copied. If comparables are unavailable or unnecessary for a narrow decision, say why.
4. Alternatives and tradeoffs - at least one credible alternative with what it improves and what it worsens.
5. Failure conditions - the conditions or new evidence that would make the recommendation wrong.
6. Next actions - a short, ordered path the user can execute.
7. Validation plan - observable acceptance behavior and proportionate checks for the first recommended step. If execution is outside scope, recommend the checks without implying they were run.

For a vague request stopped at the intake gate, the intake questions are the complete response for that turn; these deliverables apply after the user answers.

Decision Methodology

Use this framework to keep the advice reproducible instead of merely confident:

1. Constraints - identify the user's real constraints: skill level, team size, timeline, scale, budget, deployment target, compliance/security needs, and tolerance for operational complexity.
2. Comparable map - gather relevant projects or references, then label each as direct, adjacent, official/template, heavier, or lighter.
3. Transferable patterns - separate choices that transfer to this project from choices that are specific to the comparable's team, scale, history, business model, or legacy constraints.
4. Operating-cost reality - separate "free to start" from expected monthly cost, cost growth, lock-in, migration burden, and operational complexity.
5. Tradeoff matrix - compare viable options across fit, build speed, maintenance, deployment, data model, ecosystem maturity, cost model, migration risk, and failure modes. Use concise prose or a small table; avoid fake precision.
6. Recommendation - choose the path that best fits the user's constraints, not the most popular project, the loudest vendor, or the newest stack.
7. Failure conditions - state when the recommendation becomes wrong and what evidence would cause a different decision.
8. Implementation proof - turn the first recommendation into a bounded vertical slice with acceptance behavior, a focused check, and an escalation signal.

When research changes the obvious recommendation, call that out explicitly. Example: "A generic answer might choose Next.js and Postgres, but the comparable set suggests Django plus SQLite/Postgres full-text search fits this solo self-hosted scope better because..."

Before finalizing, run a quick self-check:

• Did the recommendation depend on actual project constraints rather than generic popularity?
• Did the recommendation account for real operating costs when pricing could change the decision?
• Did the answer separate comparable projects found, transferable patterns, non-transferable details, and the final recommendation?
• Did every "active", "maintained", "popular", or "production-ready" claim have evidence and an exact visible date or adoption signal?
• Did every price, quota, free-tier, or usage-limit claim come from a visible pricing/source page or get marked unverified?
• Did any section sound like a normal code review when no repo/code was inspected?
• Did the answer include when the recommended approach would become the wrong approach?
• Could the user tell whether the first recommendation worked, using an observable behavior and a proportionate check?

Implementation Proof Plan

Advice becomes useful when the user can test it. For the first recommended build slice or course correction, define:

• Slice - the smallest end-to-end behavior that creates user value or resolves the evidenced problem. Avoid horizontal setup phases that produce no observable outcome.
• Acceptance behavior - what a user, API consumer, operator, or maintainer should be able to observe when the slice works.
• Focused check - the narrowest realistic test, probe, benchmark, or inspection that could disprove the recommendation. Prefer deterministic project checks over another LLM opinion.
• Regression scope - the next broader package, integration, type, lint, build, or repository check worth running after the focused check passes.
• Escalation signal - the measured condition that justifies a heavier architecture, migration, optimization, or deeper review.

Normally the first step delivers an end-to-end slice; honor an evidenced safety or recovery prerequisite before ingesting real data or deploying. Put ordinary setup inside the slice. Make escalation signals observable: use a workload threshold, latency/error target, repeated operational burden, or named capability the current design cannot support.

Choose checks that cover the actual failure mode:

• For operations that rename, replace, delete, or migrate user data, use disposable fixtures first and a fail-closed conflict policy at the write boundary. A clean preview can become stale. Unless protected overwrite was explicitly intended, choose an operation that atomically refuses an existing destination; verify the primitive's platform semantics rather than equating atomic replacement with no-clobber. Test collisions, a destination created after preview, partial failure, and recovery. A rename log alone cannot recover overwritten content.
• For concurrency claims, use independently competing operations and a barrier, latch, or controlled schedule at the critical section. Assert the invariant on the real persistence layer. Sequential retries test retry behavior; unsynchronized parallel requests are a stress probe, not deterministic proof.
• Reserve architecture changes for demonstrated requirements or coordination needs that the existing design cannot meet. Repeated failures alone remain a debugging signal until that cause is established.

Do not prescribe TDD or a full verification ladder when the project cannot support it or when the user only asked for strategy. Keep the proof plan proportionate. For a narrow request, preserve the user's requested shape and count; embed acceptance behavior and checks inside the requested steps instead of emitting the full report contract or a duplicate Next Actions list. For mid-build reviews, do not recommend a service layer, folder split, or structural refactor merely because a pattern is fashionable; connect it to an observed failure, repeated friction, or a concrete upcoming requirement.

Local Inspection Guidance

Use the fastest available read-only tools. Prefer rg --files for file discovery. If unavailable, use the platform's normal file listing tools.

Useful evidence to inspect:

• README, docs, ADRs, architecture notes, design notes
• manifests such as package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, Gemfile, lock files
• entry points such as main.*, index.*, app.*, server.*, cli.*
• route/controller/API definitions
• domain/service modules
• data models, schemas, migrations, query layers
• auth, permissions, secrets handling, validation, serialization
• test directories, fixtures, CI workflows, lint/typecheck config
• deployment and runtime config such as Docker, compose, infra, or platform files

Do not read every file unless the project is tiny. Sampling should be purposeful, and findings should cite files or commands as evidence.