Prevent code blocks and file paths in brainstorming design docs

[pratyush618]

Fixes #649

Summary

• Added a rule to the Presenting the design section prohibiting code blocks and file paths in design docs
• Added the same rule to the After the Design → Documentation section to reinforce it when writing the spec to disk
• Both rules explain the rationale: implementation details (code, file paths) belong in the writing-plans output, and file paths go stale when files are moved

[coderabbitai]

📝 Walkthrough

Walkthrough

Two policy lines were added to skills/brainstorming/SKILL.md clarifying that design docs must not include code blocks or file paths. The additions reinforce that design docs focus on architecture and ideas, while implementation details belong in the implementation plan phase. File paths in design docs are noted as becoming stale when files are moved.

Changes

Cohort / File(s)	Summary
Design Doc Policy Clarification skills/brainstorming/SKILL.md	Added two policy lines reinforcing that design docs must exclude code blocks and file paths, emphasizing that design docs describe architecture/ideas while implementation details belong in writing-plans.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐰 A design doc pure, without code's clutter,
Just architecture dreams and ideas that flutter,
Code snippets belong in plans down the way,
Clean, lofty designs shall brighten the day! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: preventing code blocks and file paths in brainstorming design docs, which directly matches the changeset.
Description check	✅ Passed	The description is directly related to the changeset, explaining which sections were modified and the rationale for adding the new rules.
Linked Issues check	✅ Passed	The PR fully addresses issue #649 by adding rules to prevent code blocks and file paths in design docs as requested, with rationale explained in both relevant sections.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issue #649: adding policy lines to prevent code blocks and file paths in design docs. No unrelated modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

skills/brainstorming/SKILL.md (1)

86-86: Minor wording inconsistency: "file paths" vs "specific file paths".

Line 86 states "No code blocks or file paths" while line 109 says "must not contain code blocks or specific file paths." The addition of "specific" in line 109 could be interpreted to mean that general or non-specific file paths are acceptable, which likely isn't the intent.

Consider using consistent wording in both places. Options:

• Use "file paths" in both (simpler, matches line 86)
• Use "specific file paths" in both (emphasizes the concern about exact paths going stale)

♻️ Option 1: Remove "specific" for consistency

-- **Design docs must not contain code blocks or specific file paths.** Keep them focused on ideas, architecture, component descriptions, data flow, trade-offs, and success criteria. Implementation details go in the writing-plans output, not here.
+- **Design docs must not contain code blocks or file paths.** Keep them focused on ideas, architecture, component descriptions, data flow, trade-offs, and success criteria. Implementation details go in the writing-plans output, not here.

♻️ Option 2: Add "specific" to line 86 for consistency

-- **No code blocks or file paths** — design docs describe ideas and architecture, not implementation. Code snippets and specific file paths belong in the implementation plan (writing-plans), not the design doc. File paths in design docs go stale when files are moved.
+- **No code blocks or specific file paths** — design docs describe ideas and architecture, not implementation. Code snippets and specific file paths belong in the implementation plan (writing-plans), not the design doc. File paths in design docs go stale when files are moved.

Also applies to: 109-109

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@skills/brainstorming/SKILL.md` at line 86, Update the wording for consistency
between the two rules by choosing one phrase and applying it in both places:
replace "No code blocks or file paths" (the current phrase on the earlier rule)
or "must not contain code blocks or specific file paths" (the later rule) so
both use the same terminology; either use "file paths" in both lines or
"specific file paths" in both lines to remove ambiguity and ensure uniform
guidance across the document.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@skills/brainstorming/SKILL.md`:
- Line 86: Update the wording for consistency between the two rules by choosing
one phrase and applying it in both places: replace "No code blocks or file
paths" (the current phrase on the earlier rule) or "must not contain code blocks
or specific file paths" (the later rule) so both use the same terminology;
either use "file paths" in both lines or "specific file paths" in both lines to
remove ambiguity and ensure uniform guidance across the document.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 81e2df07-a17a-4ce0-a1a2-8eab3117eceb

📥 Commits

Reviewing files that changed from the base of the PR and between 33e55e6 and a7718cb.

📒 Files selected for processing (1)

• skills/brainstorming/SKILL.md