@opendirectory.dev/skills 0.1.39 → 0.1.41

package/skills/product-update-logger/evals/evals.json

@@ -0,0 +1,119 @@
+[
+  {
+    "id": "eval_001",
+    "name": "Free text only -- happy path",
+    "description": "User provides 3 items as free text. Expects all categories populated, clean content output.",
+    "input": {
+      "items": "Added dark mode|Fixed CSV export bug|Improved API speed by 40%",
+      "since": 7,
+      "repo": ""
+    },
+    "expected": {
+      "changelog_entry_has_categories": ["new", "improved", "fixed"],
+      "tweet_thread_count_min": 3,
+      "tweet_thread_count_max": 5,
+      "all_tweets_under_280_chars": true,
+      "linkedin_no_hashtags": true,
+      "linkedin_no_markdown": true,
+      "no_em_dashes": true,
+      "no_banned_words": true,
+      "no_invented_metrics": true,
+      "one_liner_under_20_words": true
+    }
+  },
+  {
+    "id": "eval_002",
+    "name": "Git commits only -- noise filtered",
+    "description": "No free text. Git log has 4 commits: 2 real, 2 noise (merge + version bump). Expects noise filtered.",
+    "input": {
+      "items": "",
+      "since": 7,
+      "repo": ""
+    },
+    "git_log_mock": [
+      "abc1234|Add user avatar upload|Users can now upload a profile picture|2026-04-21",
+      "def4567|Merge pull request #45 from user/feature||2026-04-21",
+      "ghi7890|bump version to 1.3.2||2026-04-20",
+      "jkl0123|Fix timezone bug in scheduler|Events were firing 1 hour early in non-UTC timezones|2026-04-19"
+    ],
+    "expected": {
+      "noise_filtered_count": 2,
+      "items_remaining": 2,
+      "changelog_has_new": true,
+      "changelog_has_fixed": true,
+      "merge_commit_not_in_output": true,
+      "version_bump_not_in_output": true
+    }
+  },
+  {
+    "id": "eval_003",
+    "name": "GitHub PRs as source",
+    "description": "GITHUB_TOKEN set, repo provided. Expects PRs to be fetched and used as source. PR body used for context.",
+    "input": {
+      "items": "",
+      "since": 7,
+      "repo": "acme/dashboard"
+    },
+    "mock_prs": [
+      {
+        "number": 47,
+        "title": "Fix CSV export dropping last row",
+        "body": "Regression from v1.3.1. Off-by-one error in row iterator. Fixes #102.",
+        "merged_at": "2026-04-22T10:30:00Z",
+        "labels": ["bug"]
+      },
+      {
+        "number": 48,
+        "title": "Add bulk delete to contacts list",
+        "body": "Users can now select multiple contacts and delete them at once.",
+        "merged_at": "2026-04-21T09:00:00Z",
+        "labels": []
+      }
+    ],
+    "expected": {
+      "github_available": true,
+      "pr_titles_used_as_source": true,
+      "pr_body_used_for_context": true,
+      "changelog_has_new": true,
+      "changelog_has_fixed": true,
+      "regression_context_preserved": true
+    }
+  },
+  {
+    "id": "eval_004",
+    "name": "Single item -- minimal input",
+    "description": "User provides one item. Expects no invented features, concise thread, one-liner under 20 words.",
+    "input": {
+      "items": "Fixed the login page loading slowly on mobile",
+      "since": 7,
+      "repo": ""
+    },
+    "expected": {
+      "changelog_entry_has_fixed": true,
+      "changelog_entry_has_new": false,
+      "tweet_thread_count_min": 2,
+      "tweet_thread_count_max": 3,
+      "one_liner_under_20_words": true,
+      "no_invented_additional_features": true,
+      "linkedin_mentions_mobile": true
+    }
+  },
+  {
+    "id": "eval_005",
+    "name": "Existing changelog -- correct prepend",
+    "description": "docs/changelog.md already exists with a prior entry. New run should prepend, not append. Old entry preserved.",
+    "input": {
+      "items": "Launched API v2|Deprecated old auth endpoint",
+      "since": 7,
+      "repo": ""
+    },
+    "existing_changelog": "# Changelog\n\n## Week of April 14, 2026\n\n### New\n- **Dashboard** -- New analytics dashboard with weekly summaries.\n\n---\n",
+    "expected": {
+      "new_entry_is_prepended_not_appended": true,
+      "existing_entry_still_present": true,
+      "new_label_not_equal_to_april_14": true,
+      "changelog_heading_preserved": true,
+      "api_v2_in_new_section": true
+    }
+  }
+]

package/skills/product-update-logger/references/changelog-format.md

@@ -0,0 +1,96 @@
+# Changelog Format Reference
+
+## Entry Structure
+
+```markdown
+## Week of April 23, 2026
+
+### New
+- **Feature name** -- One sentence describing what users can now do.
+
+### Improved
+- **Feature name** -- One sentence describing how the experience changed.
+
+### Fixed
+- **Feature name** -- One sentence describing what was broken and now works.
+
+### Under the hood
+- **Component** -- One sentence for developer-relevant changes only.
+
+---
+```
+
+The `---` separator goes at the bottom of each entry. Entries are prepended, so the most recent is always at the top of the file.
+
+## Category Decision Rules
+
+**New**: Use when the change adds net-new capability a user could not do before.
+- New page, new API endpoint, new integration, new toggle, new export format
+- If in doubt: can users do something they couldn't do yesterday? -> New
+
+**Improved**: Use when an existing feature is made faster, easier, more reliable, or more capable.
+- "Now 40% faster", "Works on mobile", "Added bulk actions to existing list view"
+- Performance improvements that users will notice -> Improved
+- Security patches the user doesn't see -> Under the hood
+
+**Fixed**: Something was broken and now works. Bug reports, regression fixes, crash fixes.
+- Prefer specificity: "Fixed: CSV exports no longer drop the last row"
+- If the user never knew it was broken, it can be Improved or omitted
+
+**Under the hood**: Infrastructure, dependency updates, refactoring, build changes.
+- Include only if developer-relevant: API changes, breaking changes, new environment requirements
+- Omit if the user wouldn't care
+- Never pad this section -- empty is fine
+
+## Version Label Rules
+
+**Default (date-based):**
+- `Week of [Month Day, Year]` -- e.g., "Week of April 23, 2026"
+- Use when no semver is detected in existing changelog and user didn't specify
+
+**Semver (auto-detected):**
+- If existing changelog headings match `v1.2.3` or `1.2.3` format -> use semver
+- Patch bump (x.x.+1): only if all changes are Fixed
+- Minor bump (x.+1.0): if any New feature is included
+- Show the bumped version: `v1.4.0`
+
+**Custom override:**
+- If user says "call it 'The Speed Update'" or "v2.1.0" -> use exactly that
+- Do not auto-format custom labels
+
+## Transformation Examples
+
+| Raw (commit/PR) | User-facing (changelog) |
+|---|---|
+| `Fix memory leak in worker process` | **Worker stability** -- The app no longer slows down after extended use |
+| `Add CSV export to reports page` | **Export reports** -- Download any report as a CSV from the Reports page |
+| `Improve query performance with index` | **Faster search** -- Search results now load in under half a second |
+| `Add dark mode toggle in Settings` | **Dark mode** -- Toggle it in Settings > Appearance. Works across all views |
+| `Fix timezone bug in scheduler` | **Scheduler** -- Events no longer fire an hour early in non-UTC timezones |
+| `Update dependencies to latest` | (omit -- not user-relevant) |
+| `Refactor auth middleware` | (omit unless breaking change) |
+| `Add rate limiting to API` | **API rate limits** -- Documented in the API reference. 1000 req/min per key |
+| `Fix login page slow on mobile` | **Mobile login** -- The login page now loads instantly on mobile devices |
+| `Migrate to Postgres 16` | **Database upgrade** -- Postgres 16 with improved connection pooling |
+
+## What to Omit
+
+- Test file changes
+- CI/CD pipeline changes
+- Dependency bumps (unless security-relevant)
+- Documentation-only commits
+- Version bump commits
+- Merge commits
+- Commit messages under 8 characters
+
+## Item Format
+
+```
+**[Feature name]** -- [one sentence benefit, no jargon]
+```
+
+- Feature name: 1-3 words, title case, no verbs ("Dark mode" not "Added dark mode")
+- Benefit: past tense ("Added", "Fixed", "Improved")
+- No period at end
+- No nested bullets
+- No links (links belong in the full changelog page, not the entry)

package/skills/product-update-logger/references/content-rules.md

@@ -0,0 +1,154 @@
+# Content Rules Reference
+
+## One-liner
+
+- Max 20 words
+- Cover the 1-2 biggest items
+- Plain language -- no jargon, no product name unless ambiguous
+- No period required
+- Not a tagline -- just a summary of what shipped
+
+**Good:**
+- "Dark mode, faster API, and a fix for the export bug."
+- "CSV export is live and the login bug is gone."
+- "Redesigned onboarding with two new integrations."
+
+**Bad:**
+- "Exciting new features have been released this week." (vague)
+- "We are pleased to announce several improvements to our platform." (corporate)
+- "Dark mode toggle in Settings > Appearance with full cross-view support plus 40% API response time improvement and off-by-one iterator fix." (too long)
+
+## Tweet Thread Rules
+
+**Structure (3-5 tweets):**
+- Tweet 1: Hook. "We shipped [N] things this week." OR lead with the biggest feature.
+- Tweets 2-N: One item per tweet, 1-2 sentences max. Specific, concrete.
+- Last tweet: Optional CTA -- "Changelog: [link]" or "More next week." Keep it light.
+
+**Hard rules:**
+- Each tweet strictly under 280 characters (count spaces and punctuation)
+- No hashtags -- ever
+- No em dashes (use hyphen or rewrite)
+- Active voice: "Dark mode is live" not "Dark mode has been added"
+- No promotional language ("game-changing", "revolutionize", "excited to share")
+- No markdown formatting
+- Thread numbering: 1/4, 2/4 style is optional -- skip if it feels forced
+
+**Good tweet:**
+"Dark mode is live. Toggle it in Settings > Appearance. Works everywhere."
+
+**Bad tweet:**
+"We're thrilled to announce that dark mode -- a highly requested feature -- has been added to the settings panel and is now available across all views! #darkmode #productupdate"
+
+## LinkedIn Post Rules
+
+**Format:**
+- No markdown. No asterisks (**bold** renders as **bold** on LinkedIn). No underscores.
+- No hashtags -- ever
+- Short paragraphs: 1-2 sentences, then blank line
+- Total: 150-400 words
+
+**Voice:**
+- Founder voice: "We shipped", "We fixed", "We added"
+- Not corporate: never "We are excited to announce", "We are pleased to share", "We are thrilled"
+- Direct: state the fact, then the benefit
+- Close with a question or observation, not a CTA ("What are you waiting for?" is a CTA -- avoid)
+
+**Hook (first line):**
+- Under 150 characters (LinkedIn truncates after ~210 chars before "see more")
+- "We shipped [N] updates this week." or lead with the biggest item
+- Formula options:
+  1. "We shipped [N] things this week."
+  2. "[Biggest feature] is live."
+  3. "This week: [feature], [fix], and [improvement]."
+
+**Body:**
+- One paragraph per major item (2-3 sentences max per paragraph)
+- Start with what it does, then why it matters
+- Skip Under the hood items -- users don't care
+- Blank line between paragraphs
+
+**Close:**
+- One line
+- A question that invites response: "What have you been waiting for us to ship next?"
+- Or an observation: "Smaller releases, shipped more often -- that's the goal."
+- Not: "Check out the full changelog at [link]" (that's a CTA)
+
+**Good opening:**
+```
+We shipped 3 updates this week.
+
+Dark mode is live. Toggle it in Settings under Appearance.
+
+API response time is down 40%. The dashboard now loads in under a second.
+
+We also fixed a bug where CSV exports were silently dropping the last row.
+
+What feature have you been waiting for?
+```
+
+## Email Snippet Rules
+
+**Subject line formula:**
+"What shipped this week: [biggest item] + [1 more]"
+
+Examples:
+- "What shipped this week: dark mode + faster API"
+- "What shipped this week: CSV export + 3 bug fixes"
+- "What shipped this week: onboarding redesign"
+
+**Body:**
+- 50-100 words
+- Casual, direct. Open with "Here's what we shipped this week:"
+- Bullet list of top 3-4 items with one-line descriptions
+- No marketing language
+- Appropriate for a product newsletter or drip sequence
+
+**Good:**
+```
+Subject: What shipped this week: dark mode + faster API
+
+Here's what we shipped this week:
+
+- Dark mode: toggle in Settings > Appearance
+- API response time: 40% faster, dashboard loads under 1 second
+- Fixed: CSV exports no longer drop the last row
+
+Full changelog below.
+```
+
+## Banned Words
+
+Never use these in any content piece:
+
+- powerful
+- robust
+- seamless
+- innovative
+- game-changing
+- streamline / streamlined
+- leverage
+- transform / transformative
+- revolutionize / revolutionary
+- excited to announce
+- pleased to announce
+- we are thrilled
+- cutting-edge
+- best-in-class
+- world-class
+- next-level
+- unlock
+- delightful
+
+## Anti-Patterns
+
+| Pattern | Why it's wrong |
+|---|---|
+| "We are excited to announce..." | Corporate speak. Say "We shipped." |
+| Hashtags in LinkedIn | This skill never uses hashtags |
+| **bold** in LinkedIn | Renders as literal asterisks |
+| Em dashes (--) in tweets | Use hyphen or rewrite the sentence |
+| Inventing numbers ("3x faster") | Only include metrics present in the source data |
+| Vague superlatives ("major update") | Be specific about what shipped |
+| Padding with filler items | If there's one real item, write about one item |
+| Thread recap tweet ("That's a wrap!") | Wastes a tweet -- skip it |

package/skills/product-update-logger/references/noise-filter.md

@@ -0,0 +1,86 @@
+# Noise Filter Reference
+
+## Commit Patterns to Skip
+
+These regex patterns match commits that should be excluded from the changelog:
+
+```
+^Merge (pull request|branch)\b          -- merge commits
+^(bump|update) version\b               -- version bumps
+^chore[\s:(]                           -- chore commits (chore: ..., chore(...):)
+^ci[\s:(]                              -- CI/CD commits
+^build[\s:(]                           -- build system commits
+^test[\s:(]                            -- test-only commits
+^docs[\s:(]                            -- documentation-only commits
+^style[\s:(]                           -- formatting/style commits
+^fix typo\b                            -- typo fixes
+^\s*typo\b                             -- typo commits
+^wip\b                                 -- work in progress
+^revert\b                              -- reverts (usually indicate something broken)
+^Initial commit$                       -- first commit
+^init$                                 -- init commits
+single-word subject under 8 chars      -- too vague to be useful
+```
+
+## Examples: Skip
+
+```
+Merge pull request #45 from user/feature-branch     -> skip (merge commit)
+Merge branch 'main' into feature                    -> skip (merge commit)
+bump version to 1.3.2                               -> skip (version bump)
+Update version: 2.0.1                               -> skip (version bump)
+chore: update dependencies                          -> skip (chore)
+chore(deps): bump lodash to 4.17.21                 -> skip (chore)
+ci: fix GitHub Actions workflow                     -> skip (CI)
+build: update webpack config                        -> skip (build)
+test: add unit tests for auth module                -> skip (test-only)
+docs: update README                                 -> skip (docs-only)
+style: fix linting errors                           -> skip (style)
+fix typo in error message                           -> skip (typo)
+wip: experimenting with new approach                -> skip (WIP)
+revert "Add experimental feature"                   -> skip (revert)
+Initial commit                                      -> skip
+Update                                              -> skip (single word, under 8 chars)
+Fix                                                 -> skip (single word, under 8 chars)
+```
+
+## Examples: Keep
+
+Even vague commits that don't match noise patterns should be kept and passed to the AI for judgment:
+
+```
+Update dashboard layout                             -> keep (AI will decide if useful)
+Improve error messages for API validation           -> keep
+Add dark mode toggle in Settings                    -> keep
+Fix timezone bug in scheduler                       -> keep
+Refactor authentication flow                        -> keep (even though technical)
+Increase connection pool size                       -> keep (performance-relevant)
+Add rate limiting to public API endpoints           -> keep (developer-relevant)
+Fix off-by-one error in CSV row iterator            -> keep (specific bug)
+```
+
+## PR Labels to Skip
+
+These GitHub PR labels indicate noise:
+
+```
+documentation
+chore
+dependencies
+ci
+test
+tests
+```
+
+## What the AI Does With Kept Items
+
+The AI (in Step 4 of the skill) has final discretion over:
+- Vague commits like "Update dashboard layout" -- may omit if unclear
+- "Under the hood" items -- only includes if developer-relevant
+- Categorization -- assigns each item to New, Improved, Fixed, or Under the hood
+
+The noise filter's job is to remove obvious non-user-facing commits before they reach the AI. The AI handles the judgment calls.
+
+## The Rule of Thumb
+
+If removing the commit from the list wouldn't confuse a user reading the changelog -- filter it out. If it might represent a real user-visible change (even if described technically) -- keep it and let the AI decide.