From c792a80c2fdd8e813d29443694a99bac343fc626 Mon Sep 17 00:00:00 2001 From: William Huster Date: Thu, 2 Oct 2025 17:44:30 -0400 Subject: [PATCH 1/4] Add automated writing style review GitHub Action --- .claude/agents/writing-style-reviewer.md | 200 +++++++++++++++++++++++ .github/SETUP.md | 80 +++++++++ .github/scripts/requirements.txt | 2 + .github/scripts/review-writing.py | 171 +++++++++++++++++++ .github/workflows/writing-review.yml | 41 +++++ CLAUDE.md | 13 ++ 6 files changed, 507 insertions(+) create mode 100644 .claude/agents/writing-style-reviewer.md create mode 100644 .github/SETUP.md create mode 100644 .github/scripts/requirements.txt create mode 100644 .github/scripts/review-writing.py create mode 100644 .github/workflows/writing-review.yml diff --git a/.claude/agents/writing-style-reviewer.md b/.claude/agents/writing-style-reviewer.md new file mode 100644 index 0000000..7973a0b --- /dev/null +++ b/.claude/agents/writing-style-reviewer.md @@ -0,0 +1,200 @@ +# Writing Style Reviewer Agent + +You are a writing style reviewer for ThinkNimble Research. Your role is to help writers improve their work through constructive, specific feedback. + +## Your Tone + +Be direct and critical, but supportive. You're a thoughtful colleague, not a harsh critic or a cheerleader. Point out issues clearly without sugar-coating, but acknowledge what works well. + +Think of yourself as an experienced editor who cares about the writer's growth. You notice problems that matter and explain why they matter. You don't waste time on trivial issues or empty praise. + +## Review Approach + +1. **Identify specific violations** of the style guide with line references +2. **Explain WHY** each issue matters (not just THAT it's wrong) +3. **Suggest concrete improvements** with examples +4. **Note 1-2 things done well** (but only if genuinely noteworthy) +5. **Prioritize substance over nitpicks** - focus on what affects reader understanding + +## Examples of Critical But Kind Feedback + +❌ **Don't**: "This is confusing" +✅ **Do**: "This paragraph introduces three technical terms ('DAG', 'idempotent', 'eventual consistency') without definition, which may lose readers unfamiliar with distributed systems. Consider defining 'DAG' on first use or linking to [[Directed Acyclic Graphs]]." + +❌ **Don't**: "Great work! This is amazing!" +✅ **Do**: "The concrete example in paragraph 3 (the Pokemon benchmark) effectively illustrates the abstract concept of complexity collapse. More examples like this would strengthen the piece." + +❌ **Don't**: "You used passive voice here" +✅ **Do**: "The passive construction 'mistakes were made' obscures who made the mistakes and weakens the argument. Consider: 'The team made three critical mistakes...'" + +## What NOT to Do + +- Be sycophantic or overly positive +- List minor issues without explaining their impact +- Rewrite content (suggest, don't dictate) +- Review grammar/spelling (that's what linters are for) +- Point out every small thing (prioritize what matters) + +## What to Focus On + +- **Clarity of argument**: Can readers follow the logic? +- **Evidence and citations**: Are claims backed up? Are sources linked? +- **Audience accessibility**: Will readers understand technical terms? +- **Wiki-link opportunities**: Connections to other notes? +- **Idea maturity signaling**: Is speculation marked as such? +- **Hype vs. substance**: Superlatives backed by evidence? +- **Structure**: Does the organization serve the reader? + +--- + +# ThinkNimble Research Writing Style Guidelines + +## Core Principles + +### Professional and approachable + +We write with the clarity, tone, and structure of academic work, but without unnecessary jargon. Our goal is to make complex ideas accessible to thoughtful readers. + +### Joyful curiosity + +We want to inspire others by sharing not just information, but our excitement about learning and thinking. When appropriate, let humor and personality shine through. Show that research can be fun, that learning is rewarding, and that intellectual curiosity is something to celebrate. Let your enthusiasm be contagious. + +### Passion grounded in evidence + +Our enthusiasm should come through in our writing, but it is ultimately tethered to research, data, experience, and careful reasoning. We share what excites us about a topic while maintaining intellectual honesty about limitations and uncertainties. + +### Authority with humility + +We've done our research and have valuable insights to share. We cite sources, present evidence, and make clear arguments. At the same time, we acknowledge what we don't know. We present competing viewpoints fairly, and we position ourselves as fellow learners rather than final arbiters. + +### Thoughtful perspectives, not hype + +We develop and share real opinions based on our research and experience. We recognize significant trends and changes—like AI's potential—without feeding hype cycles. We offer practical tools to help readers navigate uncertainty. We aren't entirely neutral, of course. We have our own views and stances on things. But those views are earned through investigation, not adopted for engagement and social media vanity metrics. + +### Clear and not too clever + +Every sentence should serve the reader's understanding. We favor simple words over complex ones, active voice over passive, concrete examples over abstract theories. If we can explain something in five words instead of fifteen, we do. + +### Ideas, rigorously tested + +Like software, ideas evolve through iteration and feedback. You can prototype a concept in an afternoon, but mature ideas take years of testing, refinement, and exposure to real-world complexity. We share ideas at different stages of development—some are fresh prototypes, others are thoroughly argued and battle-tested. We're transparent about where each idea sits in its lifecycle. Ideas at different stages have value, but readers deserve to know what level of thought they are getting. + +## What to Avoid + +- **Academic stuffiness**: We're rigorous, not rigid. Avoid unnecessary formality +- **Hype and superlatives**: Let the ideas speak for themselves +- **Assumed expertise**: Define terms; don't assume everyone knows what you know +- **Unexamined claims**: Every assertion should be backed by evidence or clearly marked as speculation +- **Walls of text**: Break it up; make it scannable +- **Engagement-bait hot takes**: Don't adopt positions for clicks or controversy. Our views come from investigation, not metrics +- **False neutrality**: Don't hide behind "some say..." when you have a researched perspective +- **Listicle shallowness**: "7 Ways to..." rarely does justice to complex topics. Develop ideas properly + +## Before Publishing Checklist + +- Does this represent our research honestly and accurately? +- Would this be valuable to someone encountering these ideas for the first time? +- Have I cited sources where appropriate? +- Have I signaled the maturity level of this idea? (exploring vs. tested framework) +- Does this connect to our broader knowledge base through wiki-style links? +- Have I taken a clear position, or just described what others think? +- Is my enthusiasm backed by evidence and reasoning? +- Would this make someone excited to learn more, or just informed? +- Is the structure clear and logical? +- Could I cut 20% of the words without losing meaning? + +## Voice & Tone + +- **First person plural ("we")**: "We" should be the default perspective for articles. It creates a sense of shared exploration and ownership of the research. + - It's fine to use "I" when talking about personal experiences and opinions, just make sure it's clear who is speaking. +- **Take clear positions**: State what you think and why. Avoid excessive hedging ("perhaps," "maybe," "it seems")—but be honest about uncertainty when it exists. "We believe X because Y and Z" is stronger than "It seems like X might be true." +- **Balance enthusiasm with rigor**: Let your excitement about a topic come through, but back it up. "This is fascinating because..." not just "This is amazing!" +- **Signal idea maturity**: Be explicit about whether you're sharing a fresh thought or a well-tested framework. "We're exploring..." vs. "Our research shows..." +- **Avoid hype language**: Skip superlatives (revolutionary, game-changing, unprecedented) unless you can truly defend them. Let the ideas demonstrate their significance. +- **Use concrete examples**: Abstract concepts need real-world grounding. Show, don't just tell. + +## Structure & Formatting + +- **Wiki-style linking**: Our research site is a web of knowledge. Use `[[Note Title]]` to link between articles, creating connections between related concepts. Each piece should connect to the broader knowledge base. +- **Headers structure arguments**: Use h2/h3 hierarchy to guide readers through your reasoning. Headers should preview the argument, not just label topics. +- **Develop ideas fully**: Resist listicle-style shallowness. One well-argued point beats five superficial ones. Give concepts the space they need. +- **Readable paragraphs**: Break up dense text (2-4 sentences typically), but let ideas dictate length. Don't sacrifice development for artificial brevity. + +## Citations & Sources + +Our ideas should always be grounded in evidence. + +### When to cite + +- Primary research or data: Always link to the original study, dataset, or documentation +- Surprising or counterintuitive claims: Back up anything that might make readers skeptical +- Direct quotes or paraphrases: Credit the original author +- Foundational concepts: Link to definitive explanations when introducing complex ideas + +### When citation isn't necessary + +- Common knowledge in your field: No need to cite that "Python is a programming language" +- Your own original analysis: If you ran the experiment or did the analysis, you're the source +- General observations: "Many developers prefer..." doesn't need a citation if it's widely understood + +### How to cite + +- Inline links for short citations: Link key phrases naturally: "According to recent research on developer productivity..." +- Footnotes for longer citations or asides: Use footnotes when you need to provide additional context +- Primary sources first: Link directly to the paper, documentation, or data—not to someone else's summary +- Persistent URLs: Use DOIs for academic papers, archived versions for web content when possible +- Multiple sources for contested claims: If experts disagree, acknowledge it and link to multiple perspectives + +### Claims vs. Speculation + +- **Claims require evidence**: "Studies show X" needs a link. "X correlates with Y" needs data. +- **Mark speculation clearly**: Use phrases like "We suspect...", "Our hypothesis is...", "This suggests..." when you're theorizing +- **Personal opinion gets labeled**: "In our experience..." or "We believe..." signals this is observation, not proven fact +- **Express uncertainty**: Saying "the evidence is mixed" or "this remains an open question" builds trust + +## Linking Strategy + +- **Link liberally**: Connect related concepts through `[[Wiki Links]]` +- **Make links contextual**: The link text should make sense even if you can't click it +- **Link to primary sources**: Original research, official documentation, canonical references +- **Use descriptive anchor text**: Help readers know what they're clicking + +## Terminology & Jargon + +Technical precision is important, but we must make sure that the average reader can understand us and benefit from our writing. + +- **Define on first use**: The first time you use a technical term, explain it briefly +- **Use jargon when**: Your audience knows it, no simpler alternative exists, or precision matters +- **Avoid jargon when**: Simpler words work just as well or you're excluding readers unnecessarily +- **Spell out acronyms on first use**: "Artificial Intelligence (AI)" then "AI" thereafter + +## Output Format + +Provide your review in markdown format with: + +1. **Summary** (2-3 sentences): Overall assessment of the piece +2. **Strengths** (1-2 specific things done well) +3. **Issues to Address** (organized by priority): + - Critical: Issues that significantly impact reader understanding + - Important: Issues that weaken the argument or clarity + - Minor: Suggestions for improvement (only if time permits) +4. **Specific Line-by-Line Feedback** (use line numbers or quote text) + +Example format: + +```markdown +## Summary +This piece effectively uses concrete examples to illustrate abstract concepts, making complex AI limitations accessible. However, several technical terms lack definition, and the argument would benefit from more explicit citations. + +## Strengths +- The Pokemon benchmark example (lines 45-52) effectively grounds the abstract concept of complexity collapse +- Clear section structure guides readers through the argument + +## Critical Issues +1. **Missing definitions** (line 23): "Stochastic parrot" is introduced without explanation. Consider: "...what researchers call 'stochastic parrots' - models that generate plausible-sounding text by pattern matching rather than genuine understanding." + +2. **Uncited claim** (line 67): "Studies show X" needs a source link to be credible. + +## Important Issues +[etc...] +``` diff --git a/.github/SETUP.md b/.github/SETUP.md new file mode 100644 index 0000000..c6a39d2 --- /dev/null +++ b/.github/SETUP.md @@ -0,0 +1,80 @@ +# GitHub Actions Setup for Writing Style Reviews + +This repository includes an automated writing style review system that uses Claude AI to review markdown content in pull requests. + +## How It Works + +When you open a PR that modifies files in `_notes/`, `_essays/`, or `_posts/`, a GitHub Action automatically: + +1. Detects which markdown files changed +2. Sends them to Claude with the writing-style-reviewer agent prompt +3. Posts detailed review comments on the PR +4. Provides critical but constructive feedback on writing quality + +## Setup Instructions + +### 1. Add Anthropic API Key to Repository Secrets + +1. Go to your repository settings +2. Navigate to **Secrets and variables** → **Actions** +3. Click **New repository secret** +4. Name: `ANTHROPIC_API_KEY` +5. Value: Your Anthropic API key (get one at https://console.anthropic.com/) +6. Click **Add secret** + +### 2. Enable GitHub Actions + +The workflow file is already in `.github/workflows/writing-review.yml`. It will automatically run on PRs that modify markdown files in content directories. + +### 3. Grant Permissions (if needed) + +The action needs `pull-requests: write` permission to post comments. This is configured in the workflow file and should work automatically in most setups. + +## Usage + +Simply open a PR that modifies markdown files in: +- `_notes/` +- `_essays/` +- `_posts/` + +The review will post as a comment within a few minutes. + +## Cost + +Reviews cost approximately $0.01-0.10 per file depending on length. Claude Sonnet 4.5 is used for high-quality reviews. + +## Customizing the Review Agent + +The review behavior is controlled by `.claude/agents/writing-style-reviewer.md`. To modify: + +1. Edit the agent definition file +2. Commit changes +3. Future PRs will use the updated agent + +## Disabling Reviews + +To disable automatic reviews: + +1. Delete or rename `.github/workflows/writing-review.yml` +2. Or modify the `paths` filter to exclude certain directories + +## Troubleshooting + +### Review didn't run +- Check that your PR modifies `.md` files in content directories +- Verify `ANTHROPIC_API_KEY` is set in repository secrets +- Check GitHub Actions tab for error logs + +### Review failed +- Check Actions logs for detailed error messages +- Verify API key is valid and has sufficient credits +- Ensure the agent definition file exists at `.claude/agents/writing-style-reviewer.md` + +### Review quality issues +- Modify the agent definition in `.claude/agents/writing-style-reviewer.md` +- Test changes locally using the agent before committing +- Adjust the prompt to emphasize or de-emphasize certain aspects + +## Manual Review + +You can also use the writing-style-reviewer agent manually through Claude Code by invoking it with any markdown file content. diff --git a/.github/scripts/requirements.txt b/.github/scripts/requirements.txt new file mode 100644 index 0000000..3b86339 --- /dev/null +++ b/.github/scripts/requirements.txt @@ -0,0 +1,2 @@ +anthropic>=0.39.0 +PyGithub>=2.1.1 diff --git a/.github/scripts/review-writing.py b/.github/scripts/review-writing.py new file mode 100644 index 0000000..1a4dbea --- /dev/null +++ b/.github/scripts/review-writing.py @@ -0,0 +1,171 @@ +#!/usr/bin/env python3 +""" +Writing Style Review Script for GitHub Actions + +This script reviews markdown files in PRs using the writing-style-reviewer agent. +It posts reviews as PR comments with inline feedback. +""" + +import os +import sys +from pathlib import Path +import anthropic +from github import Github + +def get_changed_markdown_files(): + """Get list of changed markdown files in content directories.""" + # Use git to find changed files + import subprocess + + # Get the base branch (usually main) + base_ref = os.environ.get('GITHUB_BASE_REF', 'main') + + # Get changed files + result = subprocess.run( + ['git', 'diff', '--name-only', f'origin/{base_ref}...HEAD'], + capture_output=True, + text=True + ) + + all_files = result.stdout.strip().split('\n') + + # Filter for markdown files in content directories + content_dirs = ['_notes/', '_essays/', '_posts/'] + changed_files = [ + f for f in all_files + if any(f.startswith(d) for d in content_dirs) and f.endswith('.md') + ] + + return changed_files + +def read_agent_definition(): + """Read the writing-style-reviewer agent definition.""" + agent_path = Path('.claude/agents/writing-style-reviewer.md') + + if not agent_path.exists(): + print(f"Error: Agent definition not found at {agent_path}") + sys.exit(1) + + return agent_path.read_text() + +def read_file_content(filepath): + """Read content of a markdown file.""" + path = Path(filepath) + + if not path.exists(): + return None + + return path.read_text() + +def review_file_with_claude(filepath, content, agent_definition): + """Send file to Claude for review using the agent definition.""" + + api_key = os.environ.get('ANTHROPIC_API_KEY') + if not api_key: + print("Error: ANTHROPIC_API_KEY environment variable not set") + sys.exit(1) + + client = anthropic.Anthropic(api_key=api_key) + + # Construct the review prompt + prompt = f"""Here is a markdown file to review: {filepath} + +---BEGIN FILE CONTENT--- +{content} +---END FILE CONTENT--- + +Please review this file according to the writing style guidelines and provide your feedback in the specified format.""" + + try: + message = client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=4096, + system=agent_definition, + messages=[ + {"role": "user", "content": prompt} + ] + ) + + return message.content[0].text + + except Exception as e: + print(f"Error calling Claude API: {e}") + return None + +def post_review_as_code_review(review_text, filepath, commit_sha): + """Post review as a proper GitHub code review.""" + + github_token = os.environ.get('GITHUB_TOKEN') + pr_number = int(os.environ.get('PR_NUMBER')) + repo_name = os.environ.get('REPO_NAME') + + if not all([github_token, pr_number, repo_name]): + print("Error: Missing GitHub environment variables") + sys.exit(1) + + g = Github(github_token) + repo = g.get_repo(repo_name) + pr = repo.get_pull(pr_number) + + # Format the review body + review_body = f"""## 📝 Writing Style Review + +{review_text} + +--- +*Review generated by [writing-style-reviewer agent](.claude/agents/writing-style-reviewer.md)* +""" + + # Post as a code review with REQUEST_CHANGES event + # Using COMMENT event to be non-blocking + pr.create_review( + commit=repo.get_commit(commit_sha), + body=review_body, + event="COMMENT", # Can be: APPROVE, REQUEST_CHANGES, or COMMENT + comments=[] # Could add inline comments here in the future + ) + print(f"✅ Posted code review for {filepath}") + +def main(): + """Main function to orchestrate the review process.""" + + print("🔍 Finding changed markdown files...") + changed_files = get_changed_markdown_files() + + if not changed_files: + print("ℹ️ No markdown files changed in content directories") + return + + print(f"📄 Found {len(changed_files)} file(s) to review:") + for f in changed_files: + print(f" - {f}") + + print("\n📖 Reading agent definition...") + agent_definition = read_agent_definition() + + # Get commit SHA for the review + commit_sha = os.environ.get('GITHUB_SHA') + if not commit_sha: + print("Error: GITHUB_SHA environment variable not set") + sys.exit(1) + + # Review each file + for filepath in changed_files: + print(f"\n🤔 Reviewing {filepath}...") + + content = read_file_content(filepath) + if not content: + print(f"⚠️ Could not read {filepath}, skipping") + continue + + review = review_file_with_claude(filepath, content, agent_definition) + + if review: + post_review_as_code_review(review, filepath, commit_sha) + else: + print(f"❌ Failed to generate review for {filepath}") + + print("\n✨ Review complete!") + +if __name__ == '__main__': + main() diff --git a/.github/workflows/writing-review.yml b/.github/workflows/writing-review.yml new file mode 100644 index 0000000..026695c --- /dev/null +++ b/.github/workflows/writing-review.yml @@ -0,0 +1,41 @@ +name: Writing Style Review + +on: + pull_request: + paths: + - '_notes/**/*.md' + - '_essays/**/*.md' + - '_posts/**/*.md' + types: [opened, synchronize] + +permissions: + pull-requests: write + contents: read + +jobs: + review: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Get full history to compare with base branch + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: | + pip install -r .github/scripts/requirements.txt + + - name: Review writing style + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + PR_NUMBER: ${{ github.event.pull_request.number }} + REPO_NAME: ${{ github.repository }} + GITHUB_SHA: ${{ github.event.pull_request.head.sha }} + run: | + python .github/scripts/review-writing.py diff --git a/CLAUDE.md b/CLAUDE.md index c028f5e..1b147af 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,6 +22,19 @@ Use this agent to create concise research notes from web links. The agent will: Example usage: When you find an interesting article, paper, or blog post that should be added to the research knowledge base. +#### writing-style-reviewer +**Location:** `.claude/agents/writing-style-reviewer.md` + +Use this agent to review markdown content against ThinkNimble Research writing style guidelines. The agent provides: +- Critical but constructive feedback on writing quality +- Specific suggestions for improvement with examples +- Checks for citation quality, clarity, and audience accessibility +- Focus on substance over grammar/spelling + +This agent is also used automatically in GitHub Actions to review PRs that modify notes, essays, or posts. + +Example usage: When reviewing draft content before publishing, or when you want feedback on how well a piece adheres to our style guidelines. + ### Global Agents (Available Across All Projects) #### git-commit-pr-manager From 6bcc9f6a4400ab811e3debd2c4e72b4ae7b51ec4 Mon Sep 17 00:00:00 2001 From: William Huster Date: Thu, 2 Oct 2025 17:47:36 -0400 Subject: [PATCH 2/4] Test: Add note changes to trigger review --- TN Research: Writing Style Guidelines.md | 358 +++++++++++++++++++++++ _notes/distribution-vs-depth.md | 9 +- _notes/pricing-value-not-time.md | 19 +- _notes/tour-of-duty-ai-era.md | 16 +- review-infinite-ui.md | 76 +++++ review-tour-of-duty-ai-era.md | 55 ++++ 6 files changed, 516 insertions(+), 17 deletions(-) create mode 100644 TN Research: Writing Style Guidelines.md create mode 100644 review-infinite-ui.md create mode 100644 review-tour-of-duty-ai-era.md diff --git a/TN Research: Writing Style Guidelines.md b/TN Research: Writing Style Guidelines.md new file mode 100644 index 0000000..c4c4eaa --- /dev/null +++ b/TN Research: Writing Style Guidelines.md @@ -0,0 +1,358 @@ +TN Research: Writing Style Guidelines +Core Principles + +Professional and approachable + +We write with the clarity, tone, and structure of academic work, but without unnecessary jargon. Our goal is to make complex ideas accessible to thoughtful readers. + +Joyful curiosity + +We want to inspire others by sharing not just information, but our excitement about learning and thinking. When appropriate, let humor and personality shine through. Show that research can be fun, that learning is rewarding, and that intellectual curiosity is something to celebrate. Let your enthusiasm be contagious. + +Passion grounded in evidence + +Our enthusiasm should come through in our writing, but it is ultimately tethered to research, data, experience, and careful reasoning. We share what excites us about a topic while maintaining intellectual honesty about limitations and uncertainties. + +Authority with humility + +We've done our research and have valuable insights to share. We cite sources, present evidence, and make clear arguments. At the same time, we acknowledge what we don't know. We present competing viewpoints fairly, and we position ourselves as fellow learners rather than final arbiters. + +Thoughtful perspectives, not hype + +We develop and share real opinions based on our research and experience. We recognize significant trends and changes—like AI's potential—without feeding hype cycles. We offer practical tools to help readers navigate uncertainty. We aren't entirely neutral, of course. We have our own views and stances on things. But those views are earned through investigation, not adopted for engagement and social media vanity metrics. + +Clear and not too clever + +Every sentence should serve the reader's understanding. We favor simple words over complex ones, active voice over passive, concrete examples over abstract theories. If we can explain something in five words instead of fifteen, we do. + +Ideas, rigorously tested + +Like software, ideas evolve through iteration and feedback. You can prototype a concept in an afternoon, but mature ideas take years of testing, refinement, and exposure to real-world complexity. We share ideas at different stages of development—some are fresh prototypes, others are thoroughly argued and battle-tested. We're transparent about where each idea sits in its lifecycle. Ideas at different stages have value, but readers deserve to know what level of thought they are getting. + +What to Avoid + +- Academic stuffiness: We're rigorous, not rigid. Avoid unnecessary formality +- Hype and superlatives: Let the ideas speak for themselves +- Assumed expertise: Define terms; don't assume everyone knows what you know +- Unexamined claims: Every assertion should be backed by evidence or clearly marked as speculation +- Walls of text: Break it up; make it scannable +- Engagement-bait hot takes: Don't adopt positions for clicks or controversy. Our views come from investigation, not metrics +- False neutrality: Don't hide behind "some say..." when you have a researched perspective +- Listicle shallowness: "7 Ways to..." rarely does justice to complex topics. Develop ideas properly + +Before Publishing + +Ask yourself: + +- Does this represent our research honestly and accurately? +- Would this be valuable to someone encountering these ideas for the first time? +- Have I cited sources where appropriate? +- Have I signaled the maturity level of this idea? (exploring vs. tested framework) +- Does this connect to our broader knowledge base through wiki-style links? +- Have I taken a clear position, or just described what others think? +- Is my enthusiasm backed by evidence and reasoning? +- Would this make someone excited to learn more, or just informed? +- Is the structure clear and logical? +- Could I cut 20% of the words without losing meaning? + +Practical checks: + +- Review the frontmatter of your new content (title, author, date, categories, excerpt, status) for accuracy +- Preview your pull request at .tn-research.pages.dev to catch formatting issues before merging + +Detailed Guidelines + +:information_source: The sections below provide more specific guidance on style, formatting, and technical content. Use these as reference when you need detailed advice on a particular aspect of writing. + +Voice & Tone + +- First person plural ("we"): "We" should be the default perspective for articles. It creates a sense of shared exploration and ownership of the research. + - It's fine to use "I" when talking about personal experiences and opinions, just make sure it's clear who is speaking. +- Take clear positions: State what you think and why. Avoid excessive hedging ("perhaps," "maybe," "it seems")—but be honest about uncertainty when it exists. "We believe X because Y and Z" is stronger than "It seems like X might be true." +- Balance enthusiasm with rigor: Let your excitement about a topic come through, but back it up. "This is fascinating because..." not just "This is amazing!" +- Signal idea maturity: Be explicit about whether you're sharing a fresh thought or a well-tested framework. "We're exploring..." vs. "Our research shows..." +- Avoid hype language: Skip superlatives (revolutionary, game-changing, unprecedented) unless you can truly defend them. Let the ideas demonstrate their significance. +- Use concrete examples: Abstract concepts need real-world grounding. Show, don't just tell. + +Structure & Formatting + +- Wiki-style linking: Our research site is a web of knowledge. Use [[Note Title]] to link between articles, creating connections between related concepts. Each piece should connect to the broader knowledge base. +- Headers structure arguments: Use h2/h3 hierarchy to guide readers through your reasoning. Headers should preview the argument, not just label topics. +- Develop ideas fully: Resist listicle-style shallowness. One well-argued point beats five superficial ones. Give concepts the space they need. +- Readable paragraphs: Break up dense text (2-4 sentences typically), but let ideas dictate length. Don't sacrifice development for artificial brevity. + +Citations & Sources + +Our ideas should always be grounded in evidence. + +When to cite: + +- Primary research or data: Always link to the original study, dataset, or documentation +- Surprising or counterintuitive claims: Back up anything that might make readers skeptical +- Direct quotes or paraphrases: Credit the original author +- Foundational concepts: Link to definitive explanations when introducing complex ideas + +When citation isn't necessary: + +- Common knowledge in your field: No need to cite that "Python is a programming language" +- Your own original analysis: If you ran the experiment or did the analysis, you're the source +- General observations: "Many developers prefer..." doesn't need a citation if it's widely understood + +How to cite: + +- Inline links for short citations: Link key phrases naturally: "According to recent research on developer productivity..." +- Footnotes for longer citations or asides: Use footnotes when you need to provide additional context, commentary, or longer bibliographic details that would interrupt the flow[^1] +- Primary sources first: Link directly to the paper, documentation, or data—not to someone else's summary +- Persistent URLs: Use DOIs for academic papers, archived versions for web content when possible +- Multiple sources for contested claims: If experts disagree, acknowledge it and link to multiple perspectives + +Footnote syntax in Markdown: + +This is a sentence with a footnote reference[^1]. + +[^1]: This is the footnote text. It can include [links](URL), multiple sentences, and additional context that would clutter the main text. The footnote will appear at the bottom of the page. + +You can also use descriptive labels instead of numbers: + +The study found significant results[^smith2023]. + +[^smith2023]: Smith, J. (2023). "Developer Productivity in Remote Teams." Journal of Software Engineering, 45(2), 123-145. https://doi.org/10.1234/example + +Claims vs. Speculation: + +- Claims require evidence: "Studies show X" needs a link. "X correlates with Y" needs data. +- Mark speculation clearly: Use phrases like "We suspect...", "Our hypothesis is...", "This suggests..." when you're theorizing +- Personal opinion gets labeled: "In our experience..." or "We believe..." signals this is observation, not proven fact +- Express uncertainty Saying "the evidence is mixed" or "this remains an open question" builds trust + +Special cases: + +- AI-assisted research: If you used AI to help summarize or analyze sources, mention it: "With assistance from Claude, we analyzed..." +- Paywalled content: Link anyway, but note when content requires access: "(paywalled)" +- Personal communications: "In conversation with [Person], they noted..." (link to their website/profile if available) + +Example: +Recent studies on remote work productivity show mixed results, with some teams reporting gains while others experience challenges. The difference often comes down to communication practices rather than technology choices. We suspect—though this hasn't been rigorously tested—that team size also plays a role. + +AI Attribution + +:robot_face: We believe in transparency about AI's role in our content creation. Every piece of content includes an attribution field in the frontmatter to clearly communicate how AI was involved. + +Attribution categories: + +- Human Written: Content created entirely by human effort without AI assistance +- AI Supported: Content created through human-AI collaboration (the most common category) +- AI Generated: Content primarily created by AI with minimal human intervention + +In the frontmatter: + +--- + +layout: post +title: "Your Article Title" +author: "Author Name" +date: 2024-03-15 +attribution: "AI Supported" + +--- + +Our philosophy: + +- We recognize AI as a tool, similar to an IDE, spell-checker, or research assistant +- We acknowledge the complexity of quantifying AI's contribution +- We prioritize transparency over precision in attribution +- We're developing this policy iteratively as the technology and our understanding evolve + +When to use each category: + +- Human Written: You wrote every word yourself, perhaps with spell-check or grammar tools +- AI Supported: You used AI to help research, draft, edit, or refine your writing (most collaborative work) +- AI Generated: AI created the bulk of the content with minimal human editing + +For our complete policy, including philosophical considerations and moral concerns, see our AI Attribution Policy. + +Linking Strategy + +Use links to create pathways for deeper exploration of our web of knowledge without cluttering your main narrative. + +Internal links (wiki-style): + +- Use double brackets: [[Note Title]] links to other notes in your knowledge base +- Link liberally: Connect related concepts, previous articles, and foundational ideas +- Make links contextual: The link text should make sense even if you can't click it + - Good: "See our previous analysis of [[Remote Work Productivity]]" + - Bad: "Click [[here]]" or "See [[this note]]" +- Create bidirectional connections: When you reference an old note, consider updating that note to link back + +External links: + +- Link to primary sources: Original research, official documentation, canonical references +- Open in context: Inline links keep readers in your article; consider context before using "open in new tab" +- Use descriptive anchor text: Help readers know what they're clicking + - Good: “Django's official documentation on migrations" + - Bad: “Link" or "Click here" +- Check link validity: Broken links erode trust. Use link checkers or archived versions when appropriate + +Link density: + +- 3-5 links per paragraph is typical for research content +- Too many links can be overwhelming; prioritize the most valuable references +- Too few links makes readers question your sources + +When to use footnotes vs. inline links: + +- Inline: Short, direct references that support the main point +- Footnote: Tangential information, longer citations, or "for the curious" asides + +Link maintenance: + +- Use archive.org or perma.cc for web content that might disappear +- For papers, prefer DOI links (e.g., https://doi.org/10.1234/example) over journal URLs +- Note when links are paywalled: ([paywalled](URL)) + +Examples: + +✅ Good linking: + +The [[Zettelkasten Method]] has gained popularity among researchers and writers. Sönke Ahrens describes it as a thinking tool, not just storage, emphasizing that connections between notes matter more than individual notes themselves. + +❌ Poor linking: + +The Zettelkasten Method has gained popularity. Click here to learn more about it. Also see this and this other thing. + +Visual Elements + +Visual content on our research site should enhance the meaning of the article, not simply decorate it. We don't use meaningless stock or AI generated images as window dressing. This goes for both images within an article and banner images that appear in social media unfurls. +:thinking_face: When in doubt, prefer text over an image, unless the image truly expresses something that text alone cannot! + +When to use visuals: + +- Screenshots: Demonstrate UI, show step-by-step processes, or highlight specific features +- Charts/graphs: Present data, trends, or comparisons +- Concept diagrams: Illustrate abstract ideas, mental models, or processes + +Image guidelines: + +- Captions add context: Explain what readers should notice: "Figure 1: The spike in latency corresponds to the cache invalidation" +- High contrast and clarity: Ensure text in images is readable; avoid low-contrast color schemes +- Consistent style: Use similar visual styles within an article + +File formats: + +- PNG for screenshots and diagrams with text +- JPG for photos +- SVG for diagrams when Mermaid isn't suitable +- Optimize all images before publishing + +Screenshots: + +- Crop tightly: Show only what's relevant +- Highlight key areas: Use boxes, arrows, or annotations to direct attention +- Privacy: Redact any sensitive information (API keys, emails, personal data) + +Charts/graphs: + +- Clear axes, titles, and labels: Every chart should be self-explanatory +- Caption with interpretation: Explain to readers what the chart means +- Honest visualization: Start Y-axis at zero unless you have good reason (and explain why) +- Accessible colors: Use colorblind-friendly palettes; don't rely on color alone to convey information + +Diagrams: + +- Mermaid syntax can be used for flowcharts, sequence diagrams, and architecture diagrams (support will be added to the site) +- Keep diagrams focused—split complex systems into multiple simpler diagrams +- Label clearly; use arrows and flow direction intentionally +- For now, diagrams can be created as images and embedded, or included as Mermaid code blocks for future rendering + +Terminology & Jargon + +Technical precision is important, but we must make make sure that the average reader can understand us and benefit from our writing. + +Introducing technical terms: + +- Define on first use: The first time you use a technical term, explain it briefly + - Good: "We used a directed acyclic graph (DAG)—a data structure with no circular dependencies—to model the workflow" + - Don't assume readers know every acronym or concept +- Link to canonical definitions: For complex concepts, link to authoritative explanations + +When to use jargon: + +- Your audience knows it: If writing for developers, "API endpoint" needs no explanation +- No simpler alternative exists: Some technical terms are the clearest way to communicate +- Precision matters: "Idempotent" means something specific that "safe to repeat" doesn't fully capture + +When to avoid jargon: + +- Simpler words work just as well: "Use" instead of "utilize," "end" instead of "terminate" +- You're excluding readers unnecessarily: If a concept can be explained in plain language, do it +- Jargon stacking: Don't pile multiple technical terms in one sentence without explanation + +Consistency: + +- Pick one term and stick with it: Don't alternate between "function," "method," and "procedure" for the same concept +- Use industry-standard terminology: Call it "React" not "React.js" (unless context demands precision) +- Create a project glossary if you find yourself using the same specialized terms repeatedly + +Acronyms: + +- Spell out on first use: "Artificial Intelligence (AI)" then "AI" thereafter +- Exception for universally known terms: HTTP, URL, API don't need spelling out in technical content +- Avoid alphabet soup: Don't write sentences like "The SLA for the API's CRUD operations via REST..." + +Code & Technical Content + +Present technical content with appropriate context so readers can grasp both what the code does and why it matters. + +Inline code vs. code blocks: + +- Inline code (backticks): Use for variable names, function calls, file paths, and short commands within sentences + - Example: "The getUserData() function returns a Promise object" +- Code blocks (triple backticks): Use for multi-line examples, complete functions, or anything requiring syntax highlighting + - Always specify the language: `python or `javascript + +Before showing code: + +- Set the context: What problem does this solve? What's the before-state? +- State your assumptions: Required dependencies, environment, or prior setup +- Explain the approach: Give readers the mental model before the implementation + +In the code itself: + +- Comments explain why, not what: Good: // Cache to avoid expensive API calls. Bad: // Set x to 5 +- Keep examples focused: Show the relevant parts. Use ... or comments to indicate omitted boilerplate +- Real code over pseudocode: When possible, show working code readers can actually run + +After the code: + +- Highlight key points: What should readers notice? What's clever or unusual? +- Note limitations: What doesn't this handle? When would you need a different approach? +- Link to full implementation: If you've condensed for clarity, provide the complete version + +Language-specific formatting: + +- Python: Follow PEP 8; prefer descriptive names over brevity +- JavaScript/TypeScript: Use modern ES6+ syntax; indicate if Node.js or browser +- Shell/Bash: Include $ prompt if showing commands; use #!/bin/bash if showing scripts +- SQL: Uppercase keywords, use clear table/column names + +Examples: + +❌ Don't do this: + +def f(x): +return x \* 2 + +✅ Do this: + +def calculate_processing_time(base_time_seconds): +""" +Estimates total processing time accounting for setup overhead. +In practice, setup typically doubles the base processing time. +""" +return base_time_seconds \* 2 + +Working examples: + +- Prefer complete, runnable code when feasible +- If posting snippets, note what's needed to run them: "This assumes you've already imported requests and set API_KEY" +- Consider linking to a full working example in a gist or repository diff --git a/_notes/distribution-vs-depth.md b/_notes/distribution-vs-depth.md index 27ea2cd..7476fe6 100644 --- a/_notes/distribution-vs-depth.md +++ b/_notes/distribution-vs-depth.md @@ -1,12 +1,12 @@ --- layout: note title: "Distribution vs Depth: Thoughts on Learning Reinvestment" -date: 2025-01-15 +date: 2025-10-02 tags: [leverage, learning, consulting, productization, agency-work] attribution: human-written status: seed authors: ["Marcy Ewald"] -summary: "" +summary: "How to extend deep, specific learning into broad applications in consulting work." --- We love our agency clients, and we love building bespoke answers to their specific needs. But, as we think about the next phase of ThinkNimble and how to extend our impact beyond the hundreds of excellent entrepreneurs we've worked with, we're asking: how can we use the Agency for a larger good? We've built hundreds of apps and provided leverage to our entreprenuers. We've learned a lot along the way. But for every learning we've had, it's extremely difficult to reinvest it. How do you extract the deep, narrow insights from bespoke client work and transform them into broadly applicable solutions? If we could do that well, how would that change our scale of impact? @@ -84,10 +84,12 @@ When we started ThinkNimble, we thought that by working with dozens of entrepren ## Two Triangles **Hormozi's Leverage Triangle**: Time → Code/Capital/Content (ascending leverage) + - Bottom: Consulting (time-intensive) - Top: Capital, code, content (scale without more time) **Our Learning Triangle**: Deep → Productized → Scaled + - Bottom: Deep agency work (1-5 clients, bespoke solutions, maximum learning depth) [this is where we've lived for 10 years] - Middle: Productized services (50-100 similar clients, templated approach, pattern recognition) [we've dabbled here] - Top: Scaled products (1:∞ scale) [the dream] @@ -95,9 +97,11 @@ When we started ThinkNimble, we thought that by working with dozens of entrepren The key insight: These triangles should feed each other. Deep work generates insights that become productized services that become scaled products. Without intentional extraction, you stay trapped at the bottom. [Ask me how I know.] ## The Reinvestment Cycle + Often, companies emerge in an opposite way - find a broad problem, create a solution, and then go down customization rabbit holes to fit it to clients' exact needs. What kind of company could we build if we reversed that learning reinvestment? The cycle could be: + 1. **Deep Work**: Solve complex problem for 1 client (e.g., billing workflow for a PT client) 2. **Extract Pattern**: Identify the reusable core (e.g., agent launcher framework) 3. **Broaden Application**: Find 50+ others with same need, productize the solution @@ -105,6 +109,7 @@ The cycle could be: ### The Distribution Test **New year bet**: If we take an agency client on, and we: + 1. Identify 50+ other organizations with the same problem 2. Build the solution with reusability in mind 3. Extract and market a generic version diff --git a/_notes/pricing-value-not-time.md b/_notes/pricing-value-not-time.md index 6aa9bf0..ff02487 100644 --- a/_notes/pricing-value-not-time.md +++ b/_notes/pricing-value-not-time.md @@ -1,21 +1,22 @@ --- layout: note title: "Pricing for Value Instead of Time" -date: 2025-01-15 +date: 2025-10-02 tags: [future-of-work, consulting, pricing, value-creation] attribution: ai-supported status: seed authors: ["Marcy Ewald"] -summary: " +summary: "Pricing not just time, but value." --- Peter and I were brainstorming last week, mostly circling around how to charge for expertise when AI makes hourly pricing obsolete. -Here's the problem: Half the MVPs we used to build can be vibe coded. Half the other half can use a good one shot prompt, some compelling UX, and excellent evals, and can solve problems that used to be only solvable by humans. If it takes me 2 months to deliver an MVP instead of 4, should I charge half as much? (I know, a lot of halves for one whole). +Here's the problem: Half the MVPs we used to build can be vibe coded. Half the other half can use a good one shot prompt, some compelling UX, and excellent evals, and can solve problems that used to be only solvable by humans. If it takes me 2 months to deliver an MVP instead of 4, should I charge half as much? (I know, a lot of halves for one whole). Maybe, if the rest of the industry has the same expertise as I do and can compete directly. Maybe, if I'm charging on hours. But, I think I'm actually now delivering value very few others can. How do I charge for that? The traditional models are breaking: + - **W2 employment**: Paid for time and "potential" over 30 years - **1099 contracting**: Paid for deliverables, usually small engagements - **Consulting**: Paid by the hour, directly punishing efficiency @@ -34,43 +35,50 @@ Translating that dark side of the moon into value-based pricing is a struggle. W ## Five Dimensions of Value -If we start to break down the value we provide outside of hours worked, it gets messy, quick. But here's one version that looks at value across five dimensions. For ThinkNimble [we've taken dozens pre-revenue companies through their seed rounds], that looks like: +If we start to break down the value we provide outside of hours worked, it gets messy, quick. But here's one version that looks at value across five dimensions. For ThinkNimble [we've taken dozens pre-revenue companies through their seed rounds], that looks like: **1. Knowledge & Learning Value** (10-30% premium) + - Multiple hypotheses to test rapidly - High pivot probability requiring flexibility - Unknown market dynamics requiring exploration - The value of preventing 6-12 months building the wrong thing **2. Speed to Market Premium** (15-50% premium) + - Racing competitors to market position - Event/demo deadlines (investor meetings, conferences) - Seasonal opportunity windows - Compressed delivery timelines **3. Future Option Value** (10-25% premium) + - Platform potential (not just single product) - API/ecosystem play possibilities - Multiple customer segment opportunities - Building flexibility for future pivots **4. Funding Catalyst Value** (20-30% of funding target) + - Active investor conversations requiring demo - Traction proof needed for raise - Fundable prototype that demonstrates viability - Typically 2-5% of next funding round target **5. Risk Mitigation Value** (10-25% premium) + - High technical uncertainty de-risking - Regulatory complexity navigation - First-time founder knowledge transfer - Strategic insights that prevent expensive mistakes **Traditional Model:** + - 400 hours × $150/hr = $60,000 **Value-Based Model:** So, if we charge on value, not time, where does that leave us? + - Base development: $60,000 - Knowledge premium (+20%): $12,000 - Speed premium (+25%): $15,000 @@ -81,7 +89,6 @@ So, if we charge on value, not time, where does that leave us? The frame: "You're not buying hours. You're buying the learning that prevents building the wrong thing, the speed that captures market timing, and the optionality that enables your next three pivots." Will that work in the real world? I don't know. But we are thinking about it, and others who have deep expertise are too. I think we'll see major changes in outcomes based pricing, especially in tech, in the next 2-3 years. - ## Related Concepts -- [[Tour of Duty in the AI Era]] - How sports-style career mobility enables this pricing model, including how workers negotiate agent development time as part of engagement compensation \ No newline at end of file +- [[Tour of Duty in the AI Era]] - How sports-style career mobility enables this pricing model, including how workers negotiate agent development time as part of engagement compensation diff --git a/_notes/tour-of-duty-ai-era.md b/_notes/tour-of-duty-ai-era.md index e7928a3..af96d8d 100644 --- a/_notes/tour-of-duty-ai-era.md +++ b/_notes/tour-of-duty-ai-era.md @@ -1,16 +1,15 @@ --- layout: note title: "Tour of Duty in the AI Era" -date: 2025-01-15 +date: 2025-10-02 tags: [future-of-work, labor-markets, consulting, ai-augmentation] attribution: human-written status: budding authors: ["Marcy Ewald"] -summary: "" +summary: "A new way of thinking about your career path." --- - -> We wrote about our concept of [tours of duty a few years ago](https://medium.com/the-business-of-tech/tours-of-duty-d4089fa9a490), and have been mulling over how to update it in the new world of AI-assisted productivty, and changes in hiring, retention, and consolidation of capital in a very few, large conglomerates. +> We wrote about our concept of [tours of duty a few years ago](https://medium.com/the-business-of-tech/tours-of-duty-d4089fa9a490), and have been mulling over how to update it in the new world of AI-assisted productivty, and changes in hiring, retention, and consolidation of capital in a very few, large conglomerates. We expect that the trend toward consolidation of resources in the hands of a few (think FANG, but with an AI spin) will continue. There will be long-tail careers available in large companies, but there will also be a huge market for talent grabbing. [there's a lot of evidence on this, from insane signing bonsues for AI talent, to layoffs of middle management. Note to self to gather these so it's easy to see what we've been reading]. @@ -39,11 +38,11 @@ From our [earlier work on tours of duty](https://medium.com/the-business-of-tech > Recently, we've gotten clearer on the actual numbers behind that investment, and their impact on pieces of our business (revenue, speed to delivery, customer value, etc.). We're slowly starting to share this with our team, hoping it helps our team understand the risks and rewards we're evaluating as we collectively invest in the tour of duty together. **Our take on tours of duty (2019 version):** + 1. Define what someone could actually accomplish in 2 years (skills they bring to the table, skills they'll work on, etc.) 2. Then, once you're clearer on the small things people can accomplish in 2 years, figure out how that translates to revenue. 3. You can do 1 without 2, but if you do 1, at some point, 2 will become clear to you, and you'll want to share it with them. - ## Agents as Hiring Signal
@@ -84,16 +83,16 @@ From our [earlier work on tours of duty](https://medium.com/the-business-of-tech
**What could a Tour of Duty look like? (2026 version):** + 1. Define what zone of genius someone has demonstrated (agents who support them, wins on their resume, etc.) 2. Understand the gaps in your competitive strategy, and whether that person plays a role in the team you need to win the next game. [link to infinite games] - - ## The Sports Model: A Third Path Professional sports already work this way: + - Athletes are constantly traded between teams - They bring specific, concentrated expertise - Compensation is front-loaded into peak years (10 years of high earnings vs. 30 years of moderate earnings) @@ -101,7 +100,6 @@ Professional sports already work this way: You bring a set of skills that fit an organization in a specific state, get paid well to "win games" together, then reinvest to retrain for the next org. You move from player, to coach, to owner. Both parties benefit from the trade when your skills and their needs overlap. -
Marcy10:56 @@ -143,10 +141,10 @@ You bring a set of skills that fit an organization in a specific state, get paid

exactly, I could go to a startup and say "you need someone who's built a product process three times, has zero interest in working here long term because they have no interest in working for a large org, and will be traded to another team as soon as you both win this Super Bowl.

- ## Tours of [Traded] Duty Deep engagement model where experts: + - Embed for concentrated periods (e.g., 6 months on, 6 months off) - Actually build and implement solutions - Bring proven expertise from multiple similar engagements diff --git a/review-infinite-ui.md b/review-infinite-ui.md new file mode 100644 index 0000000..bf4a6ab --- /dev/null +++ b/review-infinite-ui.md @@ -0,0 +1,76 @@ +# Writing Style Review: infinite-ui.md + +## Summary + +This piece presents a compelling reframing of the GenAI paradigm shift—moving the conversation away from determinism toward state space complexity. The core argument is solid and the haunted mansion metaphor is memorable. However, the draft structure feels exploratory rather than argumentative, with several technical claims lacking citations and key terms undefined. The team discussion at the end adds valuable context but dilutes the main argument. + +## Strengths + +- **Strong central thesis**: The reframing from "nondeterminism vs determinism" to "infinite state space" is a genuinely useful conceptual contribution. The chess app example (lines 34-36) effectively demonstrates combinatorial explosion in traditional software before contrasting it with GenAI's "practically infinite" space. +- **Memorable metaphors**: The haunted mansion/Frankenstein candelabra metaphor (lines 42-44) makes abstract state space complexity tangible and fun. This is exactly the kind of "joyful curiosity" the style guide calls for. + +## Critical Issues + +1. **Uncited source** (line 15): You reference "a post by an early engineer at replit" with a URL, but the link presentation is bare and informal. Consider integrating this more smoothly: "Gian Segato, an early Replit engineer who recently joined Anthropic, [argues that we're entering a probabilistic era](https://giansegato.com/essays/probabilistic-era). While I appreciate several of his insights, I believe his focus on determinism vs. probability misses the real paradigm shift." + +2. **Undefined technical terms** (lines 17-18): "Massive complex functions with practically unlimited inputs and outputs" assumes readers understand what this means in the context of neural networks. Consider briefly explaining what these "inputs and outputs" represent (tokens? parameters? possible completions?). + +3. **Mathematical notation without explanation** (lines 22-26): The F(∞) -> {∞, ∞, ∞} notation appears without context. What do the three infinity symbols in the output represent? Why three? This could confuse rather than clarify. + +4. **Epistemological vs. ontological claim needs support** (line 48): "But I don't think the difference is ontological or that it hinges on determinism. I agree with the second half of his sentence, though. The difference is epistemological." This is a strong philosophical claim that would benefit from explaining *why* you see this as epistemological rather than ontological. The distinction matters but isn't developed. + +5. **Missing wiki links**: Several concepts could connect to other notes in the knowledge base: + - "state space" (appears 11 times but never linked—could this be its own note?) + - "combinatorial explosion" (line 35) + - "temperature=0" (line 44—assuming there's content about model parameters) + +## Important Issues + +6. **Weak opening** (line 13): "This is a draft of an article / idea I might term 'Infinite UI'" reads as a placeholder. The piece is already titled "Infinite UI," so this meta-commentary undermines the authority of the argument. Consider starting directly with the thesis or with the Segato article as a jumping-off point. + +7. **"Trap" language without justification** (line 15): "IMO he is also falling into this trap focusing too much on deterministic vs. probabilistic thing." You call it a "trap" but don't explain *why* this framing is problematic until much later. Signal earlier that you'll demonstrate why this focus misleads. + +8. **Conversational fragments** (lines 28-32): The "railroad vs. sandbox," "elevator vs. wonkavator" metaphors pile up without full development. Pick the strongest one (haunted mansion works well) and develop it rather than testing multiple metaphors. + +9. **REST API security example lacks citation** (line 54): "More down to earth — this is why security is such a big problem with AI." This is a significant claim about AI security that would be strengthened by linking to examples of prompt injection, jailbreaking, or security research. + +10. **GoPursue reference assumes context** (line 56): Readers outside ThinkNimble won't know what GoPursue is. Consider: "When we were building coaching agents for GoPursue [link to case study?], our early attempts..." + +11. **Team Discussion section dilutes focus** (lines 70-114): The conversation adds interesting perspectives (especially Marcy's "spotlight vs. guardrails" metaphor), but it fragments the narrative. Consider either: + - Moving this to a separate "Discussion Notes" section at the end + - Integrating the strongest points (like the spotlight metaphor) directly into the main argument + - Creating a follow-up note that builds on these discussion points + +12. **Conclusion references "last couple of sentences"** (line 87): You're pointing to your own article structure ("hence the last couple of sentences in my article") in what appears to be part of the article itself. This meta-reference breaks the fourth wall awkwardly. + +## Minor Suggestions + +13. **Front matter status** (line 9): Status is "budding" but the content is substantial. Consider whether this should be "developing" or even "published" with appropriate caveats about it being exploratory. + +14. **Quantification of "practically infinite"** (line 38): You hedge appropriately about finite-but-astronomically-large numbers, but consider linking to actual LLM parameter counts (e.g., "GPT-4's ~1.7 trillion parameters create a state space so large...") to ground this in reality. + +15. **"fun-house mirror image"** (line 50): This metaphor works but isn't developed. Either cut it or explain what you mean by a "fun-house mirror image of the world." + +16. **Voice consistency**: The piece shifts between "I think" (line 30), "we" (line 56, in discussion), and implied "you" (line 58). Consider standardizing to "I" for personal reflection or "we" if positioning this as ThinkNimble research perspective. + +## What This Piece Does Well + +The central reframing from nondeterminism to state space complexity is valuable and could influence how people think about GenAI product design. The "adding features vs. removing features" reversal (emphasized in the team discussion) is genuinely insightful and deserves to be elevated in the main argument. Your pushback against the determinism frame is needed—people *are* overindexing on that distinction. + +## Suggested Next Steps + +1. **Clarify the structure**: Is this a response/critique of Segato's piece, or is it a standalone argument that uses his article as a starting point? Pick one and structure accordingly. + +2. **Elevate the key insights**: The "removing vs. adding features" paradigm shift and the epistemological nature of the problem deserve more prominent treatment. + +3. **Add citations**: Link to Segato's full article properly, cite AI security research, and consider linking to academic work on state space complexity in software engineering. + +4. **Decide on the discussion section**: Either integrate those insights or move them to a follow-up note. The current placement feels like you're showing your work rather than presenting a refined argument. + +5. **Consider splitting**: This could potentially become two pieces: + - **Note 1**: "Infinite State Spaces: Why GenAI is Different" (focused argument) + - **Note 2**: "Building in Infinite State Spaces: Product Design Implications" (practical applications, team discussions) + +--- + +**Final thought**: You're onto something important here. The state space framing gives product designers a better mental model than the determinism debate. Clean up the structure, add some rigor around the claims, and this could be a reference piece for how to think about GenAI product design. diff --git a/review-tour-of-duty-ai-era.md b/review-tour-of-duty-ai-era.md new file mode 100644 index 0000000..d41b9f1 --- /dev/null +++ b/review-tour-of-duty-ai-era.md @@ -0,0 +1,55 @@ +# Writing Style Review: tour-of-duty-ai-era.md + +## Summary + +This piece captures an interesting evolution of work models and includes engaging conversational snippets that show real thinking in progress. However, it reads more like brainstorming notes than a published research piece. The core ideas about tours of duty, AI augmentation, and the sports model are compelling but need development, clearer structure, and substantial citation to move from "budding" to publishable. + +## Strengths + +- **Conversational excerpts add authenticity** (lines 49-84, 105-144): The Slack/chat conversations effectively show how ideas develop through dialogue. The "bring your suite of agents" concept emerges naturally and feels fresh. +- **Sports analogy has explanatory power** (lines 96-102): The comparison to professional sports careers provides a concrete mental model for compressed, high-value employment periods. + +## Critical Issues + +1. **Missing essential context and links** (line 13): The opening references "our concept" and links to a Medium post from years ago, but readers unfamiliar with your previous work have no way to understand the original framework without clicking away. Consider summarizing the key points of the 2019 framework before diving into updates. The [[Wiki Link]] syntax isn't used where it should be—"infinite games" (line 90) is mentioned but not linked properly with bracket syntax. + +2. **Uncited claims about market trends** (line 15): "There will be long-tail careers available in large companies, but there will also be a huge market for talent grabbing" is presented as fact without evidence. The bracketed note admits sources exist but aren't included. This fundamentally weakens the argument. Either cite the evidence now (signing bonuses, layoff data) or clearly mark this as hypothesis/observation rather than established fact. + +3. **Incomplete thoughts and editorial notes left in** (lines 15-16, 90, 158): The bracketed "[there's a lot of evidence on this...]" and "[link to infinite games]" and "[link to the value note]" are editorial TODOs that should be resolved before publication. These break reader trust and signal the piece isn't ready. + +4. **Unclear argument structure** (lines 17-20): Paragraphs 3-4 introduce ideas about "the grind" and "delegable workload" without clear connection to what came before or what follows. Who is experiencing this grind? What vision is being transcribed? The logic jump is confusing. + +5. **Jargon without definition** (line 108): "disaggregation of that economic accumulation" sounds academic but obscures meaning. What does this mean in practice? Consider: "help distribute economic opportunity beyond the top 100 companies" or similar plain language. + +## Important Issues + +6. **Passive voice weakens key claims** (line 87): "What could a Tour of Duty look like?" introduces the 2026 framework, but the bullet points lack agency. "Define what zone of genius someone has demonstrated" - who is defining? The employer? Consider: "Companies should identify candidates' zones of genius..." to clarify roles and actions. + +7. **Missing signal of idea maturity** (Throughout): The piece is tagged "status: budding" which helps, but individual claims vary wildly in their development. The 2019 framework is well-documented (lines 23-44), the agents-as-hiring-signal is speculative conversation (lines 49-84), and the sports model is somewhere between. Mark speculation explicitly: "We're exploring whether..." or "An emerging pattern suggests..." + +8. **"Open Questions" section feels like writer's notes** (lines 156-162): While acknowledging uncertainty is good, this list reads more like a research agenda than insights for readers. Consider reframing these as "Key Challenges" and discussing each briefly, or integrating them into the main argument where they naturally arise. + +9. **Weak transitions between sections** (line 94): The jump from "Agents as Hiring Signal" to "The Sports Model: A Third Path" lacks connection. How do these ideas relate? Consider a transition sentence: "This agents-as-portfolio idea pairs naturally with another model we've been considering: the professional sports approach to careers." + +10. **Summary field in front matter differs from content** (line 9): The summary says "A new way of thinking about your career path" but the piece is more about *employment models* than individual career strategy. Consider: "How AI agents and sports-style trades might reshape employment relationships." + +## Minor Suggestions + +11. **Section title could be clearer** (line 147): "Tours of [Traded] Duty" is clever but the bracketed word makes it feel tentative. Either commit to "Tours of Traded Duty" or use "The Traded Model" or similar. + +12. **Voice consistency** (lines 86, 149): The piece shifts between "we" (line 13), "I" (implied in line 143 conversation), and impersonal constructions (line 87). For ThinkNimble Research, default to "we" when sharing organizational thinking, and be explicit with "I" when attributing to Marcy specifically. + +13. **Related Concepts links are incomplete** (lines 166-167): Good use of wiki-link syntax for "Pricing for Value Instead of Time" and "Agency of Agents," but these aren't introduced or connected to the main argument. A sentence explaining why these concepts matter would strengthen the knowledge web. + +## Bottom Line + +The ideas here are genuinely interesting—especially the agents-as-portfolio concept and the sports model for compressed, high-value employment. But this reads like notes toward a piece rather than a finished piece. To move from "budding" to publishable: + +1. Resolve all bracketed TODOs with actual links and citations +2. Develop the core argument: What exactly are you proposing? How does AI change tours of duty? +3. Provide evidence for market trend claims or clearly label them as hypotheses +4. Define technical/business jargon on first use +5. Connect sections with clear transitions +6. Decide whether conversational snippets are illustrative examples or primary content (they work well as examples) + +The raw material is solid. It needs structure, citations, and clarity to serve readers effectively. From f70e7098c90051c51362bab69d88c73ea50e9f87 Mon Sep 17 00:00:00 2001 From: William Huster Date: Thu, 2 Oct 2025 18:03:35 -0400 Subject: [PATCH 3/4] Only trigger reviews on ready_for_review and add filename to review --- .github/scripts/review-writing.py | 2 +- .github/workflows/writing-review.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/scripts/review-writing.py b/.github/scripts/review-writing.py index 1a4dbea..2b045c1 100644 --- a/.github/scripts/review-writing.py +++ b/.github/scripts/review-writing.py @@ -108,7 +108,7 @@ def post_review_as_code_review(review_text, filepath, commit_sha): pr = repo.get_pull(pr_number) # Format the review body - review_body = f"""## 📝 Writing Style Review + review_body = f"""## 📝 Writing Style Review: `{filepath}` {review_text} diff --git a/.github/workflows/writing-review.yml b/.github/workflows/writing-review.yml index 026695c..ad9b0f2 100644 --- a/.github/workflows/writing-review.yml +++ b/.github/workflows/writing-review.yml @@ -6,7 +6,7 @@ on: - '_notes/**/*.md' - '_essays/**/*.md' - '_posts/**/*.md' - types: [opened, synchronize] + types: [ready_for_review, synchronize] permissions: pull-requests: write From cf13e2822d91360de2a54939463edb84883b8971 Mon Sep 17 00:00:00 2001 From: William Huster Date: Thu, 2 Oct 2025 18:14:30 -0400 Subject: [PATCH 4/4] Remove synchronize trigger and add manual dispatch --- .github/workflows/writing-review.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/writing-review.yml b/.github/workflows/writing-review.yml index ad9b0f2..1bc76f1 100644 --- a/.github/workflows/writing-review.yml +++ b/.github/workflows/writing-review.yml @@ -6,7 +6,8 @@ on: - '_notes/**/*.md' - '_essays/**/*.md' - '_posts/**/*.md' - types: [ready_for_review, synchronize] + types: [ready_for_review] + workflow_dispatch: permissions: pull-requests: write