From f09410e628bf4946ed4c1dd0c1a90f953fbd25c9 Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 23 Sep 2025 21:17:10 -0700 Subject: [PATCH 1/6] docs: add prompting guideline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit introduces a new documentation page, "Prompting Guideline," which provides comprehensive instructions and best practices for interacting with Pochi. The new guide covers: - General prompting strategies. - How to craft clear, structured, and effective prompts. - Task-specific examples for various development workflows like debugging, refactoring, and feature development. Additionally, the documentation's navigation (meta.json) has been updated to include this new page under the "Resources" section. 🤖 Generated with [Pochi](https://getpochi.com) Co-Authored-By: Pochi --- packages/docs/content/docs/meta.json | 3 +- .../docs/content/docs/prompting-guideline.mdx | 143 ++++++++++++++++++ 2 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 packages/docs/content/docs/prompting-guideline.mdx diff --git a/packages/docs/content/docs/meta.json b/packages/docs/content/docs/meta.json index 5b1a0fa6a2..cb769d6698 100644 --- a/packages/docs/content/docs/meta.json +++ b/packages/docs/content/docs/meta.json @@ -26,6 +26,7 @@ "custom-agent", "---Resources---", "...developer-updates", - "tutorials" + "tutorials", + "prompting-guideline" ] } diff --git a/packages/docs/content/docs/prompting-guideline.mdx b/packages/docs/content/docs/prompting-guideline.mdx new file mode 100644 index 0000000000..2572d58a90 --- /dev/null +++ b/packages/docs/content/docs/prompting-guideline.mdx @@ -0,0 +1,143 @@ +--- +title: Prompting Guideline +description: A guide to effective prompt engineering with Pochi +icon: "Lightbulb" +--- + +# Pochi Prompting Guide + +## Intro + +Use this Prompting Guide to enhance code quality and streamline development workflows through effective prompt engineering, focusing on outcomes you can control. +Challenges like latency or cost are better addressed through model selection or configuration, not prompts. +This guide offers practical strategies to boost development workflows. + +## Overall Prompting Guidelines + +- **Provide Clear Context:** Use `@` to reference files/folders (e.g., `@api.js`) or `README.pochi.md` for project rules and goals (e.g., coding standards, security priorities). +- **Break Down Tasks:** Split complex problems into steps for stability (e.g., review, then optimize). +- **Ensure Consistency:** Rely on structured prompts (XML/JSON) for repeatable, predictable outputs. +- **Iterate Safely:** Tweak prompts step-by-step, using structure to revert changes if needed. +- **Leverage Pochi Features:** Use `~/.pochi/config.jsonc` for models & MCPs, `README.pochi.md` for agents/rules, Pochi Cloud for shared histories, GitHub/Slack for team work. + +## How to Prompt Pochi + +Effective prompting transforms vague ideas into precise actions by emphasizing clarity, examples, and structure. Approach it as directive a collaborative agent that benefits from guided, step-by-step instructions to deliver reliable results. + +### Craft Clear Prompts + +Be specific and direct. Avoid indirect phrasing like “can you", state the action explicitly. + +**Example:** “Fix `@utils.js` line 42: Add input validation for `process(data)` where `data` can be null, return a diff.” + +### Use Few Shot Prompts + +Provide 2-3 input-output examples to set expectations + +**Example:** +“Input: Error in `@hooks.js` - ‘useEffect is not defined’ in `render()`; +Output: `import { useEffect } from 'react'; useEffect(() => { console.log('mounted'); }, []);`.” + +**Example:** + “Input: Slow `@api.js` - 5s load on `/users` due to DB query; +Output: `const cache = require('node-cache'); cache.set('users', await db.query('SELECT * FROM users'), 3600);`.” + +### Let Pochi Think (Chain-of-Thought) + +For complex logic, request step-by-step reasoning. + +**E.g.,**“Debug `@main.py`: Identify the null reference issue in `fetchUser()`, propose a fix, test with `pytest test_main.py`, log the result." + +### Use Structured Prompts + +Apply structured formats (XML or JSON) for precision, repeatability, and task chaining. Use XML for hierarchical edits (e.g., nested tags) or JSON for data-driven tasks (e.g., key-value pairs). + +**XML:** +```xml + + @api.js + 42 + function validateUser(input) { return input.length; } in @api.js fails with TypeError: Cannot read property 'length' of null + + try { + if (!input) throw new TypeError('Input cannot be null'); + return validateInput(input); + } catch (e) { + logError(e, { file: '@api.js', line: 42 }); + return false; + } + + +``` + +**JSON:** +```json +{ + "task": "refactor", + "file": "@api.js", + "line": 42, + "context": "validateUser(input) fails with TypeError: Cannot read property 'length' of null", + "change": "add input validation with try-catch" +} +``` + +### Assign Pochi a Role (System Prompts) + +Specify a role in the prompt or via `.pochi/agents/` to enforce standards. + +**E.g.,** “Act as linter for `@models/db.py` per `README.pochi.md`, focusing on PEP 8 spacing issues.” + +### Chain Complex Prompts + +Divide large tasks into numbered steps for manageability. + +**E.g.,** “Step 1: Review `@api.py` for existing `/users` route, Step 2: Add `/users` GET endpoint with Flask-Login authentication.” + +## Task-Specific Applications + +This section applies prompting patterns to common development workflows, from project management to optimization. Customize these templates for your stack. + +### Project Management + +- **Initiating a New Project Phase:** “Start a new phase for `@api.js`: Initialize a `/auth` module, list dependencies, document setup separately.” +- **Reviewing Recent Changes:** “Review `@api.js`: Summarize last 3 commits’ impact on `/users`, flag issues.” +- **Syncing Team Context:** “Sync `@utils.js` changes: Compile a summary of edits across `@api.js` and `@utils.js`, share via Pochi link, align with standards.” + +### Debugging + +- **Analyzing a Crash:** “Analyze `@main.py`: Investigate why `fetchUser()` crashes with null, suggest fix, test with `pytest`.” +- **Handling Concurrency Issues:** “Debug `@main.py`: Identify deadlock in `fetchUser()` under 50 calls, propose lock fix, validate with `pytest --concurrency=5`.” +- **Handling a 500 Error:** “Handle `@api.js`: Diagnose a 500 error on `/users`, suggest a fallback, test with mock data.” +- **Handling an API Fetch Error:** “Debug `@frontend.js`: Fix a fetch error from external API, suggest retry logic (e.g., `setTimeout`), test with mock delay.” + +### Refactoring + +- **Breaking Down Functions:** “Refactor `@old.js`: Split 100-line `processData` into `validateInput` and `transformData` using ES6.” +- **Modernizing Legacy Code:** “Update `@legacy.js`: Convert PHP 5.6 loops to Node 14, preserve `/login`, test with legacy data.” +- **Optimizing Structure:** “Optimize `@api.js`: Restructure `/users` handler into smaller functions, ensure Node 16+ compatibility.” + +### Feature Development + +- **Designing a New Endpoint:** “Create a `/orders` GET in `@api.py` with Flask-Login, include auth checks.” +- **Enhancing with Validation:** “Enhance `@api.js`: Add a `/users` POST with validation, return JSON (id, name).” +- **Integrating a Tool:** “Build `@api.js`: Implement a `/deploy` POST to trigger GitHub Actions, log CI status.” +- **Triggering CI Build:** “Build `@api.js`: Add a `/ci` POST to trigger Jenkins, log build status as `{ status: pass/fail }`.” + +### Testing + +- **Testing Basic Cases:** “Test `@utils.js` `process()` with null, save to `tests/utils.test.js`.” +- **Covering Edge Cases:** “Test `@utils.js` `process()` with empty arrays and mock `{ id: 1 }`, target 85% coverage in `tests/utils.test.js`.” +- **Load Testing:** “Validate `@api.js` `/users` GET under 200 requests, use Jest with mocks, log pass rate as `{ passRate: X% }` JSON. If fails, check `@` file paths.” + +### Performance Optimization + +- **Profiling Latency:** “Profile `@api.js`: Identify `/users` bottlenecks, suggest caching (e.g., `cache.set(...)`), target <300ms latency, log as `{ latency: Xms }` JSON.” +- **Query Optimization:** “Optimize `@services/db.js`: Improve a slow SELECT query, propose an index, log performance gain as `{ gain: Y% }` JSON.” +- **Resource Check:** “Audit `@api.js`: Reduce `/users` memory usage by 20%, document changes separately.” + +### Documentation + +- **Adding Inline Comments:** “Document `@api.js`: Add comments to `/users` GET explaining auth flow.” +- **Updating Project Docs:** “Update `README.pochi.md`: Summarize `@api.js` `/users` changes, list endpoints, enforce rules.” +- **Generating API Specs:** “Create `@api.js` docs: Write OpenAPI specs for `/users` and `/orders`, save to `docs/api.md`.” + From f7298ca9c8fa335138fbdf702948ed8d67e701f9 Mon Sep 17 00:00:00 2001 From: github-actions Date: Tue, 23 Sep 2025 21:54:35 -0700 Subject: [PATCH 2/6] docs: refine prompting guideline examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Pochi](https://getpochi.com) Co-Authored-By: Pochi --- packages/docs/content/docs/prompting-guideline.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/packages/docs/content/docs/prompting-guideline.mdx b/packages/docs/content/docs/prompting-guideline.mdx index 2572d58a90..284cdb9a2b 100644 --- a/packages/docs/content/docs/prompting-guideline.mdx +++ b/packages/docs/content/docs/prompting-guideline.mdx @@ -46,7 +46,8 @@ Output: `const cache = require('node-cache'); cache.set('users', await db.query( For complex logic, request step-by-step reasoning. -**E.g.,**“Debug `@main.py`: Identify the null reference issue in `fetchUser()`, propose a fix, test with `pytest test_main.py`, log the result." +**Example:** +“Debug `@main.py`: Identify the null reference issue in `fetchUser()`, propose a fix, test with `pytest test_main.py`, log the result." ### Use Structured Prompts @@ -85,13 +86,15 @@ Apply structured formats (XML or JSON) for precision, repeatability, and task ch Specify a role in the prompt or via `.pochi/agents/` to enforce standards. -**E.g.,** “Act as linter for `@models/db.py` per `README.pochi.md`, focusing on PEP 8 spacing issues.” +**Example:** +“Act as linter for `@models/db.py` per `README.pochi.md`, focusing on PEP 8 spacing issues.” ### Chain Complex Prompts Divide large tasks into numbered steps for manageability. -**E.g.,** “Step 1: Review `@api.py` for existing `/users` route, Step 2: Add `/users` GET endpoint with Flask-Login authentication.” +**Example:** +“Step 1: Review `@api.py` for existing `/users` route, Step 2: Add `/users` GET endpoint with Flask-Login authentication.” ## Task-Specific Applications @@ -131,7 +134,7 @@ This section applies prompting patterns to common development workflows, from pr ### Performance Optimization -- **Profiling Latency:** “Profile `@api.js`: Identify `/users` bottlenecks, suggest caching (e.g., `cache.set(...)`), target <300ms latency, log as `{ latency: Xms }` JSON.” +- **Profiling Latency:** “Profile `@api.js`: Identify `/users` bottlenecks, suggest caching (e.g., `cache.set(...)`), target `<300ms` latency, log as `{ latency: Xms }` JSON.” - **Query Optimization:** “Optimize `@services/db.js`: Improve a slow SELECT query, propose an index, log performance gain as `{ gain: Y% }` JSON.” - **Resource Check:** “Audit `@api.js`: Reduce `/users` memory usage by 20%, document changes separately.” @@ -140,4 +143,3 @@ This section applies prompting patterns to common development workflows, from pr - **Adding Inline Comments:** “Document `@api.js`: Add comments to `/users` GET explaining auth flow.” - **Updating Project Docs:** “Update `README.pochi.md`: Summarize `@api.js` `/users` changes, list endpoints, enforce rules.” - **Generating API Specs:** “Create `@api.js` docs: Write OpenAPI specs for `/users` and `/orders`, save to `docs/api.md`.” - From 4c64953a2ab3e7cdd24c1b1ccdf27c4cfc3b1a8a Mon Sep 17 00:00:00 2001 From: github-actions Date: Wed, 24 Sep 2025 11:54:37 -0700 Subject: [PATCH 3/6] fix(docs): resolve build errors in prompting guideline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Corrected invalid frontmatter syntax. - Escaped special characters causing MDX parsing failures. - Fixed malformed XML example block. 🤖 Generated with [Pochi](https://getpochi.com) Co-Authored-By: Pochi --- packages/docs/content/docs/prompting-guideline.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/packages/docs/content/docs/prompting-guideline.mdx b/packages/docs/content/docs/prompting-guideline.mdx index 284cdb9a2b..6e9e7dfae2 100644 --- a/packages/docs/content/docs/prompting-guideline.mdx +++ b/packages/docs/content/docs/prompting-guideline.mdx @@ -57,8 +57,7 @@ Apply structured formats (XML or JSON) for precision, repeatability, and task ch ```xml @api.js - 42 - function validateUser(input) { return input.length; } in @api.js fails with TypeError: Cannot read property 'length' of null + 42 function validateUser(input) { return input.length; } in @api.js fails with TypeError: Cannot read property 'length' of null try { if (!input) throw new TypeError('Input cannot be null'); @@ -134,7 +133,7 @@ This section applies prompting patterns to common development workflows, from pr ### Performance Optimization -- **Profiling Latency:** “Profile `@api.js`: Identify `/users` bottlenecks, suggest caching (e.g., `cache.set(...)`), target `<300ms` latency, log as `{ latency: Xms }` JSON.” +- **Profiling Latency:** “Profile `@api.js`: Identify `/users` bottlenecks, suggest caching (e.g., `cache.set(...)`), target `<300ms` latency, log as `{ latency: Xms }` JSON.” - **Query Optimization:** “Optimize `@services/db.js`: Improve a slow SELECT query, propose an index, log performance gain as `{ gain: Y% }` JSON.” - **Resource Check:** “Audit `@api.js`: Reduce `/users` memory usage by 20%, document changes separately.” From f368c87d6b8662af3cd27938eb83d5f3dfc422da Mon Sep 17 00:00:00 2001 From: github-actions Date: Sat, 27 Sep 2025 18:48:52 -0700 Subject: [PATCH 4/6] fix(docs): clarify and correct prompting guidelines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Clarified the meaning of 'structure' in prompts to refer to structured formats like XML or JSON. - Corrected and expanded the 'Leverage Pochi Features' section to be more accurate and readable, detailing the specific files and directories for rules, workflows, and custom agents based on verified documentation. 🤖 Generated with [Pochi](https://getpochi.com) Co-Authored-By: Pochi --- packages/docs/content/docs/prompting-guideline.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/packages/docs/content/docs/prompting-guideline.mdx b/packages/docs/content/docs/prompting-guideline.mdx index 6e9e7dfae2..3af1f89596 100644 --- a/packages/docs/content/docs/prompting-guideline.mdx +++ b/packages/docs/content/docs/prompting-guideline.mdx @@ -17,8 +17,14 @@ This guide offers practical strategies to boost development workflows. - **Provide Clear Context:** Use `@` to reference files/folders (e.g., `@api.js`) or `README.pochi.md` for project rules and goals (e.g., coding standards, security priorities). - **Break Down Tasks:** Split complex problems into steps for stability (e.g., review, then optimize). - **Ensure Consistency:** Rely on structured prompts (XML/JSON) for repeatable, predictable outputs. -- **Iterate Safely:** Tweak prompts step-by-step, using structure to revert changes if needed. -- **Leverage Pochi Features:** Use `~/.pochi/config.jsonc` for models & MCPs, `README.pochi.md` for agents/rules, Pochi Cloud for shared histories, GitHub/Slack for team work. +- **Iterate Safely:** Tweak prompts step-by-step. Using structured formats like XML or JSON for your prompts makes it easier to track and revert changes if needed. +- **Leverage Pochi Features:** + - Use `~/.pochi/config.jsonc` for models & MCPs. + - Use `README.pochi.md` for project-specific rules. + - Use `.pochi/workflows/` for custom workflows. + - Use `.pochi/agents/` for custom agents. + - Use Pochi Cloud for sharing task histories. + - Use the GitHub & Slack integrations for team collaboration. ## How to Prompt Pochi From 60f3e36997d684b871088804811774a760bab353 Mon Sep 17 00:00:00 2001 From: Lucy Gao Date: Sun, 28 Sep 2025 13:54:28 +0800 Subject: [PATCH 5/6] Adjust intro section. --- packages/docs/content/docs/prompting-guideline.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/packages/docs/content/docs/prompting-guideline.mdx b/packages/docs/content/docs/prompting-guideline.mdx index 3af1f89596..da310da9a5 100644 --- a/packages/docs/content/docs/prompting-guideline.mdx +++ b/packages/docs/content/docs/prompting-guideline.mdx @@ -8,9 +8,7 @@ icon: "Lightbulb" ## Intro -Use this Prompting Guide to enhance code quality and streamline development workflows through effective prompt engineering, focusing on outcomes you can control. -Challenges like latency or cost are better addressed through model selection or configuration, not prompts. -This guide offers practical strategies to boost development workflows. +Welcome to Pochi Prompting Guideline! Please consider using this doc as reference to help you write more effective prompts, guiding Pochi to better understand your instructions, and thus maximizing your dev experience with Pochi. ## Overall Prompting Guidelines From 26f8ac7e95acfaaf69f30fd95107fee5eb066d19 Mon Sep 17 00:00:00 2001 From: github-actions Date: Mon, 29 Sep 2025 13:05:40 -0700 Subject: [PATCH 6/6] docs: add links to prompting guideline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds relevant links to the prompting guideline documentation for features like the CLI, rules, workflows, custom agents, and integrations. Also clarifies the language around sharing features to avoid confusion. 🤖 Generated with [Pochi](https://getpochi.com) Co-Authored-By: Pochi --- .../docs/content/docs/prompting-guideline.mdx | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/packages/docs/content/docs/prompting-guideline.mdx b/packages/docs/content/docs/prompting-guideline.mdx index da310da9a5..e60647b5cc 100644 --- a/packages/docs/content/docs/prompting-guideline.mdx +++ b/packages/docs/content/docs/prompting-guideline.mdx @@ -17,12 +17,12 @@ Welcome to Pochi Prompting Guideline! Please consider using this doc as referenc - **Ensure Consistency:** Rely on structured prompts (XML/JSON) for repeatable, predictable outputs. - **Iterate Safely:** Tweak prompts step-by-step. Using structured formats like XML or JSON for your prompts makes it easier to track and revert changes if needed. - **Leverage Pochi Features:** - - Use `~/.pochi/config.jsonc` for models & MCPs. - - Use `README.pochi.md` for project-specific rules. - - Use `.pochi/workflows/` for custom workflows. - - Use `.pochi/agents/` for custom agents. - - Use Pochi Cloud for sharing task histories. - - Use the GitHub & Slack integrations for team collaboration. + - Use `~/.pochi/config.jsonc` for [models](/models) & [MCPs](/mcp). + - Use `README.pochi.md` for [project-specific rules](/rules). + - Use `.pochi/workflows/` for [custom workflows](/workflows). + - Use `.pochi/agents/` for [custom agents](/custom-agent). + - Use [Pochi's sharing features](/share) to share task histories. + - Use the [GitHub](/github) & [Slack](/slack) integrations for team collaboration. ## How to Prompt Pochi @@ -61,7 +61,8 @@ Apply structured formats (XML or JSON) for precision, repeatability, and task ch ```xml @api.js - 42 function validateUser(input) { return input.length; } in @api.js fails with TypeError: Cannot read property 'length' of null + 42 + function validateUser(input) { return input.length; } in @api.js fails with TypeError: Cannot read property 'length' of null try { if (!input) throw new TypeError('Input cannot be null'); @@ -87,7 +88,7 @@ Apply structured formats (XML or JSON) for precision, repeatability, and task ch ### Assign Pochi a Role (System Prompts) -Specify a role in the prompt or via `.pochi/agents/` to enforce standards. +Specify a role in the prompt or via a [custom agent](/custom-agent) to enforce standards. **Example:** “Act as linter for `@models/db.py` per `README.pochi.md`, focusing on PEP 8 spacing issues.” @@ -107,7 +108,7 @@ This section applies prompting patterns to common development workflows, from pr - **Initiating a New Project Phase:** “Start a new phase for `@api.js`: Initialize a `/auth` module, list dependencies, document setup separately.” - **Reviewing Recent Changes:** “Review `@api.js`: Summarize last 3 commits’ impact on `/users`, flag issues.” -- **Syncing Team Context:** “Sync `@utils.js` changes: Compile a summary of edits across `@api.js` and `@utils.js`, share via Pochi link, align with standards.” +- **Syncing Team Context:** “Sync `@utils.js` changes: Compile a summary of edits across `@api.js` and `@utils.js`, share via [Pochi link](/share), align with standards.” ### Debugging