@wazir-dev/cli 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (629) hide show
  1. package/AGENTS.md +111 -0
  2. package/CHANGELOG.md +14 -0
  3. package/CONTRIBUTING.md +101 -0
  4. package/LICENSE +21 -0
  5. package/README.md +314 -0
  6. package/assets/composition-engine.mmd +34 -0
  7. package/assets/demo-script.sh +17 -0
  8. package/assets/logo-dark.svg +14 -0
  9. package/assets/logo.svg +14 -0
  10. package/assets/pipeline.mmd +39 -0
  11. package/assets/record-demo.sh +51 -0
  12. package/docs/README.md +51 -0
  13. package/docs/adapters/context-mode.md +60 -0
  14. package/docs/concepts/architecture.md +87 -0
  15. package/docs/concepts/artifact-model.md +60 -0
  16. package/docs/concepts/composition-engine.md +36 -0
  17. package/docs/concepts/indexing-and-recall.md +160 -0
  18. package/docs/concepts/observability.md +41 -0
  19. package/docs/concepts/roles-and-workflows.md +59 -0
  20. package/docs/concepts/terminology-policy.md +27 -0
  21. package/docs/getting-started/01-installation.md +78 -0
  22. package/docs/getting-started/02-first-run.md +102 -0
  23. package/docs/getting-started/03-adding-to-project.md +15 -0
  24. package/docs/getting-started/04-host-setup.md +15 -0
  25. package/docs/guides/ci-integration.md +15 -0
  26. package/docs/guides/creating-skills.md +15 -0
  27. package/docs/guides/expertise-module-authoring.md +15 -0
  28. package/docs/guides/hook-development.md +15 -0
  29. package/docs/guides/memory-and-learnings.md +34 -0
  30. package/docs/guides/multi-host-export.md +15 -0
  31. package/docs/guides/troubleshooting.md +101 -0
  32. package/docs/guides/writing-custom-roles.md +15 -0
  33. package/docs/plans/2026-03-15-cli-pipeline-integration-design.md +592 -0
  34. package/docs/plans/2026-03-15-cli-pipeline-integration-plan.md +598 -0
  35. package/docs/plans/2026-03-15-docs-enforcement-plan.md +238 -0
  36. package/docs/readmes/INDEX.md +99 -0
  37. package/docs/readmes/features/expertise/README.md +171 -0
  38. package/docs/readmes/features/exports/README.md +222 -0
  39. package/docs/readmes/features/hooks/README.md +103 -0
  40. package/docs/readmes/features/hooks/loop-cap-guard.md +133 -0
  41. package/docs/readmes/features/hooks/post-tool-capture.md +121 -0
  42. package/docs/readmes/features/hooks/post-tool-lint.md +130 -0
  43. package/docs/readmes/features/hooks/pre-compact-summary.md +122 -0
  44. package/docs/readmes/features/hooks/pre-tool-capture-route.md +100 -0
  45. package/docs/readmes/features/hooks/protected-path-write-guard.md +128 -0
  46. package/docs/readmes/features/hooks/session-start.md +119 -0
  47. package/docs/readmes/features/hooks/stop-handoff-harvest.md +125 -0
  48. package/docs/readmes/features/roles/README.md +157 -0
  49. package/docs/readmes/features/roles/clarifier.md +152 -0
  50. package/docs/readmes/features/roles/content-author.md +190 -0
  51. package/docs/readmes/features/roles/designer.md +193 -0
  52. package/docs/readmes/features/roles/executor.md +184 -0
  53. package/docs/readmes/features/roles/learner.md +210 -0
  54. package/docs/readmes/features/roles/planner.md +182 -0
  55. package/docs/readmes/features/roles/researcher.md +164 -0
  56. package/docs/readmes/features/roles/reviewer.md +184 -0
  57. package/docs/readmes/features/roles/specifier.md +162 -0
  58. package/docs/readmes/features/roles/verifier.md +215 -0
  59. package/docs/readmes/features/schemas/README.md +178 -0
  60. package/docs/readmes/features/skills/README.md +63 -0
  61. package/docs/readmes/features/skills/brainstorming.md +96 -0
  62. package/docs/readmes/features/skills/debugging.md +148 -0
  63. package/docs/readmes/features/skills/design.md +120 -0
  64. package/docs/readmes/features/skills/prepare-next.md +109 -0
  65. package/docs/readmes/features/skills/run-audit.md +159 -0
  66. package/docs/readmes/features/skills/scan-project.md +109 -0
  67. package/docs/readmes/features/skills/self-audit.md +176 -0
  68. package/docs/readmes/features/skills/tdd.md +137 -0
  69. package/docs/readmes/features/skills/using-skills.md +92 -0
  70. package/docs/readmes/features/skills/verification.md +120 -0
  71. package/docs/readmes/features/skills/writing-plans.md +104 -0
  72. package/docs/readmes/features/tooling/README.md +320 -0
  73. package/docs/readmes/features/workflows/README.md +186 -0
  74. package/docs/readmes/features/workflows/author.md +181 -0
  75. package/docs/readmes/features/workflows/clarify.md +154 -0
  76. package/docs/readmes/features/workflows/design-review.md +171 -0
  77. package/docs/readmes/features/workflows/design.md +169 -0
  78. package/docs/readmes/features/workflows/discover.md +162 -0
  79. package/docs/readmes/features/workflows/execute.md +173 -0
  80. package/docs/readmes/features/workflows/learn.md +167 -0
  81. package/docs/readmes/features/workflows/plan-review.md +165 -0
  82. package/docs/readmes/features/workflows/plan.md +170 -0
  83. package/docs/readmes/features/workflows/prepare-next.md +167 -0
  84. package/docs/readmes/features/workflows/review.md +169 -0
  85. package/docs/readmes/features/workflows/run-audit.md +191 -0
  86. package/docs/readmes/features/workflows/spec-challenge.md +159 -0
  87. package/docs/readmes/features/workflows/specify.md +160 -0
  88. package/docs/readmes/features/workflows/verify.md +177 -0
  89. package/docs/readmes/packages/README.md +50 -0
  90. package/docs/readmes/packages/ajv.md +117 -0
  91. package/docs/readmes/packages/context-mode.md +118 -0
  92. package/docs/readmes/packages/gray-matter.md +116 -0
  93. package/docs/readmes/packages/node-test.md +137 -0
  94. package/docs/readmes/packages/yaml.md +112 -0
  95. package/docs/reference/configuration-reference.md +159 -0
  96. package/docs/reference/expertise-index.md +52 -0
  97. package/docs/reference/git-flow.md +43 -0
  98. package/docs/reference/hooks.md +87 -0
  99. package/docs/reference/host-exports.md +50 -0
  100. package/docs/reference/launch-checklist.md +172 -0
  101. package/docs/reference/marketplace-listings.md +76 -0
  102. package/docs/reference/release-process.md +34 -0
  103. package/docs/reference/roles-reference.md +77 -0
  104. package/docs/reference/skills.md +33 -0
  105. package/docs/reference/templates.md +29 -0
  106. package/docs/reference/tooling-cli.md +94 -0
  107. package/docs/truth-claims.yaml +222 -0
  108. package/expertise/PROGRESS.md +63 -0
  109. package/expertise/README.md +18 -0
  110. package/expertise/antipatterns/PROGRESS.md +56 -0
  111. package/expertise/antipatterns/backend/api-design-antipatterns.md +1271 -0
  112. package/expertise/antipatterns/backend/auth-antipatterns.md +1195 -0
  113. package/expertise/antipatterns/backend/caching-antipatterns.md +622 -0
  114. package/expertise/antipatterns/backend/database-antipatterns.md +1038 -0
  115. package/expertise/antipatterns/backend/index.md +24 -0
  116. package/expertise/antipatterns/backend/microservices-antipatterns.md +850 -0
  117. package/expertise/antipatterns/code/architecture-antipatterns.md +919 -0
  118. package/expertise/antipatterns/code/async-antipatterns.md +622 -0
  119. package/expertise/antipatterns/code/code-smells.md +1186 -0
  120. package/expertise/antipatterns/code/dependency-antipatterns.md +1209 -0
  121. package/expertise/antipatterns/code/error-handling-antipatterns.md +1360 -0
  122. package/expertise/antipatterns/code/index.md +27 -0
  123. package/expertise/antipatterns/code/naming-and-abstraction.md +1118 -0
  124. package/expertise/antipatterns/code/state-management-antipatterns.md +1076 -0
  125. package/expertise/antipatterns/code/testing-antipatterns.md +1053 -0
  126. package/expertise/antipatterns/design/accessibility-antipatterns.md +1136 -0
  127. package/expertise/antipatterns/design/dark-patterns.md +1121 -0
  128. package/expertise/antipatterns/design/index.md +22 -0
  129. package/expertise/antipatterns/design/ui-antipatterns.md +1202 -0
  130. package/expertise/antipatterns/design/ux-antipatterns.md +680 -0
  131. package/expertise/antipatterns/frontend/css-layout-antipatterns.md +691 -0
  132. package/expertise/antipatterns/frontend/flutter-antipatterns.md +1827 -0
  133. package/expertise/antipatterns/frontend/index.md +23 -0
  134. package/expertise/antipatterns/frontend/mobile-antipatterns.md +573 -0
  135. package/expertise/antipatterns/frontend/react-antipatterns.md +1128 -0
  136. package/expertise/antipatterns/frontend/spa-antipatterns.md +1235 -0
  137. package/expertise/antipatterns/index.md +31 -0
  138. package/expertise/antipatterns/performance/index.md +20 -0
  139. package/expertise/antipatterns/performance/performance-antipatterns.md +1013 -0
  140. package/expertise/antipatterns/performance/premature-optimization.md +623 -0
  141. package/expertise/antipatterns/performance/scaling-antipatterns.md +785 -0
  142. package/expertise/antipatterns/process/ai-coding-antipatterns.md +853 -0
  143. package/expertise/antipatterns/process/code-review-antipatterns.md +656 -0
  144. package/expertise/antipatterns/process/deployment-antipatterns.md +920 -0
  145. package/expertise/antipatterns/process/index.md +23 -0
  146. package/expertise/antipatterns/process/technical-debt-antipatterns.md +647 -0
  147. package/expertise/antipatterns/security/index.md +20 -0
  148. package/expertise/antipatterns/security/secrets-antipatterns.md +849 -0
  149. package/expertise/antipatterns/security/security-theater.md +843 -0
  150. package/expertise/antipatterns/security/vulnerability-patterns.md +801 -0
  151. package/expertise/architecture/PROGRESS.md +70 -0
  152. package/expertise/architecture/data/caching-architecture.md +671 -0
  153. package/expertise/architecture/data/data-consistency.md +574 -0
  154. package/expertise/architecture/data/data-modeling.md +536 -0
  155. package/expertise/architecture/data/event-streams-and-queues.md +634 -0
  156. package/expertise/architecture/data/index.md +25 -0
  157. package/expertise/architecture/data/search-architecture.md +663 -0
  158. package/expertise/architecture/data/sql-vs-nosql.md +708 -0
  159. package/expertise/architecture/decisions/architecture-decision-records.md +640 -0
  160. package/expertise/architecture/decisions/build-vs-buy.md +616 -0
  161. package/expertise/architecture/decisions/index.md +23 -0
  162. package/expertise/architecture/decisions/monolith-to-microservices.md +790 -0
  163. package/expertise/architecture/decisions/technology-selection.md +616 -0
  164. package/expertise/architecture/distributed/cap-theorem-and-tradeoffs.md +800 -0
  165. package/expertise/architecture/distributed/circuit-breaker-bulkhead.md +741 -0
  166. package/expertise/architecture/distributed/consensus-and-coordination.md +796 -0
  167. package/expertise/architecture/distributed/distributed-systems-fundamentals.md +564 -0
  168. package/expertise/architecture/distributed/idempotency-and-retry.md +796 -0
  169. package/expertise/architecture/distributed/index.md +25 -0
  170. package/expertise/architecture/distributed/saga-pattern.md +797 -0
  171. package/expertise/architecture/foundations/architectural-thinking.md +460 -0
  172. package/expertise/architecture/foundations/coupling-and-cohesion.md +770 -0
  173. package/expertise/architecture/foundations/design-principles-solid.md +649 -0
  174. package/expertise/architecture/foundations/domain-driven-design.md +719 -0
  175. package/expertise/architecture/foundations/index.md +25 -0
  176. package/expertise/architecture/foundations/separation-of-concerns.md +472 -0
  177. package/expertise/architecture/foundations/twelve-factor-app.md +797 -0
  178. package/expertise/architecture/index.md +34 -0
  179. package/expertise/architecture/integration/api-design-graphql.md +638 -0
  180. package/expertise/architecture/integration/api-design-grpc.md +804 -0
  181. package/expertise/architecture/integration/api-design-rest.md +892 -0
  182. package/expertise/architecture/integration/index.md +25 -0
  183. package/expertise/architecture/integration/third-party-integration.md +795 -0
  184. package/expertise/architecture/integration/webhooks-and-callbacks.md +1152 -0
  185. package/expertise/architecture/integration/websockets-realtime.md +791 -0
  186. package/expertise/architecture/mobile-architecture/index.md +22 -0
  187. package/expertise/architecture/mobile-architecture/mobile-app-architecture.md +780 -0
  188. package/expertise/architecture/mobile-architecture/mobile-backend-for-frontend.md +670 -0
  189. package/expertise/architecture/mobile-architecture/offline-first.md +719 -0
  190. package/expertise/architecture/mobile-architecture/push-and-sync.md +782 -0
  191. package/expertise/architecture/patterns/cqrs-event-sourcing.md +717 -0
  192. package/expertise/architecture/patterns/event-driven.md +797 -0
  193. package/expertise/architecture/patterns/hexagonal-clean-architecture.md +870 -0
  194. package/expertise/architecture/patterns/index.md +27 -0
  195. package/expertise/architecture/patterns/layered-architecture.md +736 -0
  196. package/expertise/architecture/patterns/microservices.md +753 -0
  197. package/expertise/architecture/patterns/modular-monolith.md +692 -0
  198. package/expertise/architecture/patterns/monolith.md +626 -0
  199. package/expertise/architecture/patterns/plugin-architecture.md +735 -0
  200. package/expertise/architecture/patterns/serverless.md +780 -0
  201. package/expertise/architecture/scaling/database-scaling.md +615 -0
  202. package/expertise/architecture/scaling/feature-flags-and-rollouts.md +757 -0
  203. package/expertise/architecture/scaling/horizontal-vs-vertical.md +606 -0
  204. package/expertise/architecture/scaling/index.md +24 -0
  205. package/expertise/architecture/scaling/multi-tenancy.md +800 -0
  206. package/expertise/architecture/scaling/stateless-design.md +787 -0
  207. package/expertise/backend/embedded-firmware.md +625 -0
  208. package/expertise/backend/go.md +853 -0
  209. package/expertise/backend/index.md +24 -0
  210. package/expertise/backend/java-spring.md +448 -0
  211. package/expertise/backend/node-typescript.md +625 -0
  212. package/expertise/backend/python-fastapi.md +724 -0
  213. package/expertise/backend/rust.md +458 -0
  214. package/expertise/backend/solidity.md +711 -0
  215. package/expertise/composition-map.yaml +443 -0
  216. package/expertise/content/foundations/content-modeling.md +395 -0
  217. package/expertise/content/foundations/editorial-standards.md +449 -0
  218. package/expertise/content/foundations/index.md +24 -0
  219. package/expertise/content/foundations/microcopy.md +455 -0
  220. package/expertise/content/foundations/terminology-governance.md +509 -0
  221. package/expertise/content/index.md +34 -0
  222. package/expertise/content/patterns/accessibility-copy.md +518 -0
  223. package/expertise/content/patterns/index.md +24 -0
  224. package/expertise/content/patterns/notification-content.md +433 -0
  225. package/expertise/content/patterns/sample-content.md +486 -0
  226. package/expertise/content/patterns/state-copy.md +439 -0
  227. package/expertise/design/PROGRESS.md +58 -0
  228. package/expertise/design/disciplines/dark-mode-theming.md +577 -0
  229. package/expertise/design/disciplines/design-systems.md +595 -0
  230. package/expertise/design/disciplines/index.md +25 -0
  231. package/expertise/design/disciplines/information-architecture.md +800 -0
  232. package/expertise/design/disciplines/interaction-design.md +788 -0
  233. package/expertise/design/disciplines/responsive-design.md +552 -0
  234. package/expertise/design/disciplines/usability-testing.md +516 -0
  235. package/expertise/design/disciplines/user-research.md +792 -0
  236. package/expertise/design/foundations/accessibility-design.md +796 -0
  237. package/expertise/design/foundations/color-theory.md +797 -0
  238. package/expertise/design/foundations/iconography.md +795 -0
  239. package/expertise/design/foundations/index.md +26 -0
  240. package/expertise/design/foundations/motion-and-animation.md +653 -0
  241. package/expertise/design/foundations/rtl-design.md +585 -0
  242. package/expertise/design/foundations/spacing-and-layout.md +607 -0
  243. package/expertise/design/foundations/typography.md +800 -0
  244. package/expertise/design/foundations/visual-hierarchy.md +761 -0
  245. package/expertise/design/index.md +32 -0
  246. package/expertise/design/patterns/authentication-flows.md +474 -0
  247. package/expertise/design/patterns/content-consumption.md +789 -0
  248. package/expertise/design/patterns/data-display.md +618 -0
  249. package/expertise/design/patterns/e-commerce.md +1494 -0
  250. package/expertise/design/patterns/feedback-and-states.md +642 -0
  251. package/expertise/design/patterns/forms-and-input.md +819 -0
  252. package/expertise/design/patterns/gamification.md +801 -0
  253. package/expertise/design/patterns/index.md +31 -0
  254. package/expertise/design/patterns/microinteractions.md +449 -0
  255. package/expertise/design/patterns/navigation.md +800 -0
  256. package/expertise/design/patterns/notifications.md +705 -0
  257. package/expertise/design/patterns/onboarding.md +700 -0
  258. package/expertise/design/patterns/search-and-filter.md +601 -0
  259. package/expertise/design/patterns/settings-and-preferences.md +768 -0
  260. package/expertise/design/patterns/social-and-community.md +748 -0
  261. package/expertise/design/platforms/desktop-native.md +612 -0
  262. package/expertise/design/platforms/index.md +25 -0
  263. package/expertise/design/platforms/mobile-android.md +825 -0
  264. package/expertise/design/platforms/mobile-cross-platform.md +983 -0
  265. package/expertise/design/platforms/mobile-ios.md +699 -0
  266. package/expertise/design/platforms/tablet.md +794 -0
  267. package/expertise/design/platforms/web-dashboard.md +790 -0
  268. package/expertise/design/platforms/web-responsive.md +550 -0
  269. package/expertise/design/psychology/behavioral-nudges.md +449 -0
  270. package/expertise/design/psychology/cognitive-load.md +1191 -0
  271. package/expertise/design/psychology/error-psychology.md +778 -0
  272. package/expertise/design/psychology/index.md +22 -0
  273. package/expertise/design/psychology/persuasive-design.md +736 -0
  274. package/expertise/design/psychology/user-mental-models.md +623 -0
  275. package/expertise/design/tooling/open-pencil.md +266 -0
  276. package/expertise/frontend/angular.md +1073 -0
  277. package/expertise/frontend/desktop-electron.md +546 -0
  278. package/expertise/frontend/flutter.md +782 -0
  279. package/expertise/frontend/index.md +27 -0
  280. package/expertise/frontend/native-android.md +409 -0
  281. package/expertise/frontend/native-ios.md +490 -0
  282. package/expertise/frontend/react-native.md +1160 -0
  283. package/expertise/frontend/react.md +808 -0
  284. package/expertise/frontend/vue.md +1089 -0
  285. package/expertise/humanize/domain-rules-code.md +79 -0
  286. package/expertise/humanize/domain-rules-content.md +67 -0
  287. package/expertise/humanize/domain-rules-technical-docs.md +56 -0
  288. package/expertise/humanize/index.md +35 -0
  289. package/expertise/humanize/self-audit-checklist.md +87 -0
  290. package/expertise/humanize/sentence-patterns.md +218 -0
  291. package/expertise/humanize/vocabulary-blacklist.md +105 -0
  292. package/expertise/i18n/PROGRESS.md +65 -0
  293. package/expertise/i18n/advanced/accessibility-and-i18n.md +28 -0
  294. package/expertise/i18n/advanced/bidirectional-text-algorithm.md +38 -0
  295. package/expertise/i18n/advanced/complex-scripts.md +30 -0
  296. package/expertise/i18n/advanced/performance-and-i18n.md +27 -0
  297. package/expertise/i18n/advanced/testing-i18n.md +28 -0
  298. package/expertise/i18n/content/content-adaptation.md +23 -0
  299. package/expertise/i18n/content/locale-specific-formatting.md +23 -0
  300. package/expertise/i18n/content/machine-translation-integration.md +28 -0
  301. package/expertise/i18n/content/translation-management.md +29 -0
  302. package/expertise/i18n/foundations/date-time-calendars.md +67 -0
  303. package/expertise/i18n/foundations/i18n-architecture.md +272 -0
  304. package/expertise/i18n/foundations/locale-and-language-tags.md +79 -0
  305. package/expertise/i18n/foundations/numbers-currency-units.md +61 -0
  306. package/expertise/i18n/foundations/pluralization-and-gender.md +109 -0
  307. package/expertise/i18n/foundations/string-externalization.md +236 -0
  308. package/expertise/i18n/foundations/text-direction-bidi.md +241 -0
  309. package/expertise/i18n/foundations/unicode-and-encoding.md +86 -0
  310. package/expertise/i18n/index.md +38 -0
  311. package/expertise/i18n/platform/backend-i18n.md +31 -0
  312. package/expertise/i18n/platform/flutter-i18n.md +148 -0
  313. package/expertise/i18n/platform/native-android-i18n.md +36 -0
  314. package/expertise/i18n/platform/native-ios-i18n.md +36 -0
  315. package/expertise/i18n/platform/react-i18n.md +103 -0
  316. package/expertise/i18n/platform/web-css-i18n.md +81 -0
  317. package/expertise/i18n/rtl/arabic-specific.md +175 -0
  318. package/expertise/i18n/rtl/hebrew-specific.md +149 -0
  319. package/expertise/i18n/rtl/rtl-animations-and-transitions.md +111 -0
  320. package/expertise/i18n/rtl/rtl-forms-and-input.md +161 -0
  321. package/expertise/i18n/rtl/rtl-fundamentals.md +211 -0
  322. package/expertise/i18n/rtl/rtl-icons-and-images.md +181 -0
  323. package/expertise/i18n/rtl/rtl-layout-mirroring.md +252 -0
  324. package/expertise/i18n/rtl/rtl-navigation-and-gestures.md +107 -0
  325. package/expertise/i18n/rtl/rtl-testing-and-qa.md +147 -0
  326. package/expertise/i18n/rtl/rtl-typography.md +160 -0
  327. package/expertise/index.md +113 -0
  328. package/expertise/index.yaml +216 -0
  329. package/expertise/infrastructure/cloud-aws.md +597 -0
  330. package/expertise/infrastructure/cloud-gcp.md +599 -0
  331. package/expertise/infrastructure/cybersecurity.md +816 -0
  332. package/expertise/infrastructure/database-mongodb.md +447 -0
  333. package/expertise/infrastructure/database-postgres.md +400 -0
  334. package/expertise/infrastructure/devops-cicd.md +787 -0
  335. package/expertise/infrastructure/index.md +27 -0
  336. package/expertise/performance/PROGRESS.md +50 -0
  337. package/expertise/performance/backend/api-latency.md +1204 -0
  338. package/expertise/performance/backend/background-jobs.md +506 -0
  339. package/expertise/performance/backend/connection-pooling.md +1209 -0
  340. package/expertise/performance/backend/database-query-optimization.md +515 -0
  341. package/expertise/performance/backend/index.md +23 -0
  342. package/expertise/performance/backend/rate-limiting-and-throttling.md +971 -0
  343. package/expertise/performance/foundations/algorithmic-complexity.md +954 -0
  344. package/expertise/performance/foundations/caching-strategies.md +489 -0
  345. package/expertise/performance/foundations/concurrency-and-parallelism.md +847 -0
  346. package/expertise/performance/foundations/index.md +24 -0
  347. package/expertise/performance/foundations/measuring-and-profiling.md +440 -0
  348. package/expertise/performance/foundations/memory-management.md +964 -0
  349. package/expertise/performance/foundations/performance-budgets.md +1314 -0
  350. package/expertise/performance/index.md +31 -0
  351. package/expertise/performance/infrastructure/auto-scaling.md +1059 -0
  352. package/expertise/performance/infrastructure/cdn-and-edge.md +1081 -0
  353. package/expertise/performance/infrastructure/index.md +22 -0
  354. package/expertise/performance/infrastructure/load-balancing.md +1081 -0
  355. package/expertise/performance/infrastructure/observability.md +1079 -0
  356. package/expertise/performance/mobile/index.md +23 -0
  357. package/expertise/performance/mobile/mobile-animations.md +544 -0
  358. package/expertise/performance/mobile/mobile-memory-battery.md +416 -0
  359. package/expertise/performance/mobile/mobile-network.md +452 -0
  360. package/expertise/performance/mobile/mobile-rendering.md +599 -0
  361. package/expertise/performance/mobile/mobile-startup-time.md +505 -0
  362. package/expertise/performance/platform-specific/flutter-performance.md +647 -0
  363. package/expertise/performance/platform-specific/index.md +22 -0
  364. package/expertise/performance/platform-specific/node-performance.md +1307 -0
  365. package/expertise/performance/platform-specific/postgres-performance.md +1366 -0
  366. package/expertise/performance/platform-specific/react-performance.md +1403 -0
  367. package/expertise/performance/web/bundle-optimization.md +1239 -0
  368. package/expertise/performance/web/image-and-media.md +636 -0
  369. package/expertise/performance/web/index.md +24 -0
  370. package/expertise/performance/web/network-optimization.md +1133 -0
  371. package/expertise/performance/web/rendering-performance.md +1098 -0
  372. package/expertise/performance/web/ssr-and-hydration.md +918 -0
  373. package/expertise/performance/web/web-vitals.md +1374 -0
  374. package/expertise/quality/accessibility.md +985 -0
  375. package/expertise/quality/evidence-based-verification.md +499 -0
  376. package/expertise/quality/index.md +24 -0
  377. package/expertise/quality/ml-model-audit.md +614 -0
  378. package/expertise/quality/performance.md +600 -0
  379. package/expertise/quality/testing-api.md +891 -0
  380. package/expertise/quality/testing-mobile.md +496 -0
  381. package/expertise/quality/testing-web.md +849 -0
  382. package/expertise/security/PROGRESS.md +54 -0
  383. package/expertise/security/agentic-identity.md +540 -0
  384. package/expertise/security/compliance-frameworks.md +601 -0
  385. package/expertise/security/data/data-encryption.md +364 -0
  386. package/expertise/security/data/data-privacy-gdpr.md +692 -0
  387. package/expertise/security/data/database-security.md +1171 -0
  388. package/expertise/security/data/index.md +22 -0
  389. package/expertise/security/data/pii-handling.md +531 -0
  390. package/expertise/security/foundations/authentication.md +1041 -0
  391. package/expertise/security/foundations/authorization.md +603 -0
  392. package/expertise/security/foundations/cryptography.md +1001 -0
  393. package/expertise/security/foundations/index.md +25 -0
  394. package/expertise/security/foundations/owasp-top-10.md +1354 -0
  395. package/expertise/security/foundations/secrets-management.md +1217 -0
  396. package/expertise/security/foundations/secure-sdlc.md +700 -0
  397. package/expertise/security/foundations/supply-chain-security.md +698 -0
  398. package/expertise/security/index.md +31 -0
  399. package/expertise/security/infrastructure/cloud-security-aws.md +1296 -0
  400. package/expertise/security/infrastructure/cloud-security-gcp.md +1376 -0
  401. package/expertise/security/infrastructure/container-security.md +721 -0
  402. package/expertise/security/infrastructure/incident-response.md +1295 -0
  403. package/expertise/security/infrastructure/index.md +24 -0
  404. package/expertise/security/infrastructure/logging-and-monitoring.md +1618 -0
  405. package/expertise/security/infrastructure/network-security.md +1337 -0
  406. package/expertise/security/mobile/index.md +23 -0
  407. package/expertise/security/mobile/mobile-android-security.md +1218 -0
  408. package/expertise/security/mobile/mobile-binary-protection.md +1229 -0
  409. package/expertise/security/mobile/mobile-data-storage.md +1265 -0
  410. package/expertise/security/mobile/mobile-ios-security.md +1401 -0
  411. package/expertise/security/mobile/mobile-network-security.md +1520 -0
  412. package/expertise/security/smart-contract-security.md +594 -0
  413. package/expertise/security/testing/index.md +22 -0
  414. package/expertise/security/testing/penetration-testing.md +1258 -0
  415. package/expertise/security/testing/security-code-review.md +1765 -0
  416. package/expertise/security/testing/threat-modeling.md +1074 -0
  417. package/expertise/security/testing/vulnerability-scanning.md +1062 -0
  418. package/expertise/security/web/api-security.md +586 -0
  419. package/expertise/security/web/cors-and-headers.md +433 -0
  420. package/expertise/security/web/csrf.md +562 -0
  421. package/expertise/security/web/file-upload.md +1477 -0
  422. package/expertise/security/web/index.md +25 -0
  423. package/expertise/security/web/injection.md +1375 -0
  424. package/expertise/security/web/session-management.md +1101 -0
  425. package/expertise/security/web/xss.md +1158 -0
  426. package/exports/README.md +17 -0
  427. package/exports/hosts/claude/.claude/agents/clarifier.md +42 -0
  428. package/exports/hosts/claude/.claude/agents/content-author.md +63 -0
  429. package/exports/hosts/claude/.claude/agents/designer.md +55 -0
  430. package/exports/hosts/claude/.claude/agents/executor.md +55 -0
  431. package/exports/hosts/claude/.claude/agents/learner.md +51 -0
  432. package/exports/hosts/claude/.claude/agents/planner.md +53 -0
  433. package/exports/hosts/claude/.claude/agents/researcher.md +43 -0
  434. package/exports/hosts/claude/.claude/agents/reviewer.md +54 -0
  435. package/exports/hosts/claude/.claude/agents/specifier.md +47 -0
  436. package/exports/hosts/claude/.claude/agents/verifier.md +71 -0
  437. package/exports/hosts/claude/.claude/commands/author.md +42 -0
  438. package/exports/hosts/claude/.claude/commands/clarify.md +38 -0
  439. package/exports/hosts/claude/.claude/commands/design-review.md +46 -0
  440. package/exports/hosts/claude/.claude/commands/design.md +44 -0
  441. package/exports/hosts/claude/.claude/commands/discover.md +37 -0
  442. package/exports/hosts/claude/.claude/commands/execute.md +48 -0
  443. package/exports/hosts/claude/.claude/commands/learn.md +38 -0
  444. package/exports/hosts/claude/.claude/commands/plan-review.md +42 -0
  445. package/exports/hosts/claude/.claude/commands/plan.md +39 -0
  446. package/exports/hosts/claude/.claude/commands/prepare-next.md +37 -0
  447. package/exports/hosts/claude/.claude/commands/review.md +40 -0
  448. package/exports/hosts/claude/.claude/commands/run-audit.md +41 -0
  449. package/exports/hosts/claude/.claude/commands/spec-challenge.md +41 -0
  450. package/exports/hosts/claude/.claude/commands/specify.md +38 -0
  451. package/exports/hosts/claude/.claude/commands/verify.md +37 -0
  452. package/exports/hosts/claude/.claude/settings.json +34 -0
  453. package/exports/hosts/claude/CLAUDE.md +19 -0
  454. package/exports/hosts/claude/export.manifest.json +38 -0
  455. package/exports/hosts/claude/host-package.json +67 -0
  456. package/exports/hosts/codex/AGENTS.md +19 -0
  457. package/exports/hosts/codex/export.manifest.json +38 -0
  458. package/exports/hosts/codex/host-package.json +41 -0
  459. package/exports/hosts/cursor/.cursor/hooks.json +16 -0
  460. package/exports/hosts/cursor/.cursor/rules/wazir-core.mdc +19 -0
  461. package/exports/hosts/cursor/export.manifest.json +38 -0
  462. package/exports/hosts/cursor/host-package.json +42 -0
  463. package/exports/hosts/gemini/GEMINI.md +19 -0
  464. package/exports/hosts/gemini/export.manifest.json +38 -0
  465. package/exports/hosts/gemini/host-package.json +41 -0
  466. package/hooks/README.md +18 -0
  467. package/hooks/definitions/loop_cap_guard.yaml +21 -0
  468. package/hooks/definitions/post_tool_capture.yaml +24 -0
  469. package/hooks/definitions/pre_compact_summary.yaml +19 -0
  470. package/hooks/definitions/pre_tool_capture_route.yaml +19 -0
  471. package/hooks/definitions/protected_path_write_guard.yaml +19 -0
  472. package/hooks/definitions/session_start.yaml +19 -0
  473. package/hooks/definitions/stop_handoff_harvest.yaml +20 -0
  474. package/hooks/loop-cap-guard +17 -0
  475. package/hooks/post-tool-lint +36 -0
  476. package/hooks/protected-path-write-guard +17 -0
  477. package/hooks/session-start +41 -0
  478. package/llms-full.txt +2355 -0
  479. package/llms.txt +43 -0
  480. package/package.json +79 -0
  481. package/roles/README.md +20 -0
  482. package/roles/clarifier.md +42 -0
  483. package/roles/content-author.md +63 -0
  484. package/roles/designer.md +55 -0
  485. package/roles/executor.md +55 -0
  486. package/roles/learner.md +51 -0
  487. package/roles/planner.md +53 -0
  488. package/roles/researcher.md +43 -0
  489. package/roles/reviewer.md +54 -0
  490. package/roles/specifier.md +47 -0
  491. package/roles/verifier.md +71 -0
  492. package/schemas/README.md +24 -0
  493. package/schemas/accepted-learning.schema.json +20 -0
  494. package/schemas/author-artifact.schema.json +156 -0
  495. package/schemas/clarification.schema.json +19 -0
  496. package/schemas/design-artifact.schema.json +80 -0
  497. package/schemas/docs-claim.schema.json +18 -0
  498. package/schemas/export-manifest.schema.json +20 -0
  499. package/schemas/hook.schema.json +67 -0
  500. package/schemas/host-export-package.schema.json +18 -0
  501. package/schemas/implementation-plan.schema.json +19 -0
  502. package/schemas/proposed-learning.schema.json +19 -0
  503. package/schemas/research.schema.json +18 -0
  504. package/schemas/review.schema.json +29 -0
  505. package/schemas/run-manifest.schema.json +18 -0
  506. package/schemas/spec-challenge.schema.json +18 -0
  507. package/schemas/spec.schema.json +20 -0
  508. package/schemas/usage.schema.json +102 -0
  509. package/schemas/verification-proof.schema.json +29 -0
  510. package/schemas/wazir-manifest.schema.json +173 -0
  511. package/skills/README.md +40 -0
  512. package/skills/brainstorming/SKILL.md +77 -0
  513. package/skills/debugging/SKILL.md +50 -0
  514. package/skills/design/SKILL.md +61 -0
  515. package/skills/dispatching-parallel-agents/SKILL.md +128 -0
  516. package/skills/executing-plans/SKILL.md +70 -0
  517. package/skills/finishing-a-development-branch/SKILL.md +169 -0
  518. package/skills/humanize/SKILL.md +123 -0
  519. package/skills/init-pipeline/SKILL.md +124 -0
  520. package/skills/prepare-next/SKILL.md +20 -0
  521. package/skills/receiving-code-review/SKILL.md +123 -0
  522. package/skills/requesting-code-review/SKILL.md +105 -0
  523. package/skills/requesting-code-review/code-reviewer.md +108 -0
  524. package/skills/run-audit/SKILL.md +197 -0
  525. package/skills/scan-project/SKILL.md +41 -0
  526. package/skills/self-audit/SKILL.md +153 -0
  527. package/skills/subagent-driven-development/SKILL.md +154 -0
  528. package/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
  529. package/skills/subagent-driven-development/implementer-prompt.md +102 -0
  530. package/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  531. package/skills/tdd/SKILL.md +23 -0
  532. package/skills/using-git-worktrees/SKILL.md +163 -0
  533. package/skills/using-skills/SKILL.md +95 -0
  534. package/skills/verification/SKILL.md +22 -0
  535. package/skills/wazir/SKILL.md +463 -0
  536. package/skills/writing-plans/SKILL.md +30 -0
  537. package/skills/writing-skills/SKILL.md +157 -0
  538. package/skills/writing-skills/anthropic-best-practices.md +122 -0
  539. package/skills/writing-skills/persuasion-principles.md +50 -0
  540. package/templates/README.md +20 -0
  541. package/templates/artifacts/README.md +10 -0
  542. package/templates/artifacts/accepted-learning.md +19 -0
  543. package/templates/artifacts/accepted-learning.template.json +12 -0
  544. package/templates/artifacts/author.md +74 -0
  545. package/templates/artifacts/author.template.json +19 -0
  546. package/templates/artifacts/clarification.md +21 -0
  547. package/templates/artifacts/clarification.template.json +12 -0
  548. package/templates/artifacts/execute-notes.md +19 -0
  549. package/templates/artifacts/implementation-plan.md +21 -0
  550. package/templates/artifacts/implementation-plan.template.json +11 -0
  551. package/templates/artifacts/learning-proposal.md +19 -0
  552. package/templates/artifacts/next-run-handoff.md +21 -0
  553. package/templates/artifacts/plan-review.md +19 -0
  554. package/templates/artifacts/proposed-learning.template.json +12 -0
  555. package/templates/artifacts/research.md +21 -0
  556. package/templates/artifacts/research.template.json +12 -0
  557. package/templates/artifacts/review-findings.md +19 -0
  558. package/templates/artifacts/review.template.json +11 -0
  559. package/templates/artifacts/run-manifest.template.json +8 -0
  560. package/templates/artifacts/spec-challenge.md +19 -0
  561. package/templates/artifacts/spec-challenge.template.json +11 -0
  562. package/templates/artifacts/spec.md +21 -0
  563. package/templates/artifacts/spec.template.json +12 -0
  564. package/templates/artifacts/verification-proof.md +19 -0
  565. package/templates/artifacts/verification-proof.template.json +11 -0
  566. package/templates/examples/accepted-learning.example.json +14 -0
  567. package/templates/examples/author.example.json +152 -0
  568. package/templates/examples/clarification.example.json +15 -0
  569. package/templates/examples/docs-claim.example.json +8 -0
  570. package/templates/examples/export-manifest.example.json +7 -0
  571. package/templates/examples/host-export-package.example.json +11 -0
  572. package/templates/examples/implementation-plan.example.json +17 -0
  573. package/templates/examples/proposed-learning.example.json +13 -0
  574. package/templates/examples/research.example.json +15 -0
  575. package/templates/examples/research.example.md +6 -0
  576. package/templates/examples/review.example.json +17 -0
  577. package/templates/examples/run-manifest.example.json +9 -0
  578. package/templates/examples/spec-challenge.example.json +14 -0
  579. package/templates/examples/spec.example.json +21 -0
  580. package/templates/examples/verification-proof.example.json +21 -0
  581. package/templates/examples/wazir-manifest.example.yaml +65 -0
  582. package/templates/task-definition-schema.md +99 -0
  583. package/tooling/README.md +20 -0
  584. package/tooling/src/adapters/context-mode.js +50 -0
  585. package/tooling/src/capture/command.js +376 -0
  586. package/tooling/src/capture/store.js +99 -0
  587. package/tooling/src/capture/usage.js +270 -0
  588. package/tooling/src/checks/branches.js +50 -0
  589. package/tooling/src/checks/brand-truth.js +110 -0
  590. package/tooling/src/checks/changelog.js +231 -0
  591. package/tooling/src/checks/command-registry.js +36 -0
  592. package/tooling/src/checks/commits.js +102 -0
  593. package/tooling/src/checks/docs-drift.js +103 -0
  594. package/tooling/src/checks/docs-truth.js +201 -0
  595. package/tooling/src/checks/runtime-surface.js +156 -0
  596. package/tooling/src/cli.js +116 -0
  597. package/tooling/src/command-options.js +56 -0
  598. package/tooling/src/commands/validate.js +320 -0
  599. package/tooling/src/doctor/command.js +91 -0
  600. package/tooling/src/export/command.js +77 -0
  601. package/tooling/src/export/compiler.js +498 -0
  602. package/tooling/src/guards/loop-cap-guard.js +52 -0
  603. package/tooling/src/guards/protected-path-write-guard.js +67 -0
  604. package/tooling/src/index/command.js +152 -0
  605. package/tooling/src/index/storage.js +1061 -0
  606. package/tooling/src/index/summarizers.js +261 -0
  607. package/tooling/src/loaders.js +18 -0
  608. package/tooling/src/project-root.js +22 -0
  609. package/tooling/src/recall/command.js +225 -0
  610. package/tooling/src/schema-validator.js +30 -0
  611. package/tooling/src/state-root.js +40 -0
  612. package/tooling/src/status/command.js +71 -0
  613. package/wazir.manifest.yaml +135 -0
  614. package/workflows/README.md +19 -0
  615. package/workflows/author.md +42 -0
  616. package/workflows/clarify.md +38 -0
  617. package/workflows/design-review.md +46 -0
  618. package/workflows/design.md +44 -0
  619. package/workflows/discover.md +37 -0
  620. package/workflows/execute.md +48 -0
  621. package/workflows/learn.md +38 -0
  622. package/workflows/plan-review.md +42 -0
  623. package/workflows/plan.md +39 -0
  624. package/workflows/prepare-next.md +37 -0
  625. package/workflows/review.md +40 -0
  626. package/workflows/run-audit.md +41 -0
  627. package/workflows/spec-challenge.md +41 -0
  628. package/workflows/specify.md +38 -0
  629. package/workflows/verify.md +37 -0
@@ -0,0 +1,800 @@
1
+ # Information Architecture (IA) — Expertise Module
2
+
3
+ > Information architecture is the practice of structuring, organizing, labeling, and designing navigation and search systems so that people can find and understand information effectively. IA sits at the intersection of user mental models, content strategy, and interaction design. It determines whether users succeed or fail at locating information and completing tasks. The discipline draws on library science, cognitive psychology, and systems thinking to create structures that feel intuitive, scale gracefully, and support both human wayfinding and machine discoverability.
4
+
5
+ ---
6
+
7
+ ## 1. What This Discipline Covers
8
+
9
+ Information architecture encompasses four interdependent systems, as defined by Rosenfeld, Morville, and Arango in *Information Architecture: For the Web and Beyond* (4th edition):
10
+
11
+ ### 1.1 Organization Systems
12
+
13
+ Organization systems determine how content is grouped, categorized, and structured. They answer the question: "How do we classify this information?"
14
+
15
+ **Exact Organization Schemes** — unambiguous, mutually exclusive categories:
16
+ - Alphabetical — dictionary, directory, or glossary ordering
17
+ - Chronological — timelines, archives, event sequences
18
+ - Geographical — location-based grouping (maps, regional content)
19
+
20
+ **Ambiguous Organization Schemes** — require intellectual interpretation, harder to design but often more useful:
21
+ - Topical — by subject matter (most common scheme for content-heavy sites)
22
+ - Task-oriented — organized around what users want to do (e.g., "Pay a bill," "Track an order")
23
+ - Audience-specific — segmented by user type (e.g., "For Students," "For Faculty," "For Alumni")
24
+ - Metaphor-driven — using a familiar concept to explain an unfamiliar structure (use sparingly; metaphors break down)
25
+ - Hybrid — combining multiple schemes (common in practice; requires careful execution to avoid confusion)
26
+
27
+ **Organization Structures** define relationships between content groups:
28
+ - Hierarchy (taxonomy) — top-down tree structure; the backbone of most IAs
29
+ - Heterarchy (database model) — flat, metadata-driven; items belong to multiple categories
30
+ - Hypertext — associative linking; supports non-linear exploration
31
+ - Sequential — linear progression (wizards, tutorials, onboarding flows)
32
+ - Polyhierarchy — items legitimately live in multiple locations in the hierarchy (NNG recommends this for items users expect in more than one place, but warns against overuse)
33
+
34
+ ### 1.2 Labeling Systems
35
+
36
+ Labels are the words and phrases used to represent categories, links, headings, and options. Poor labeling is one of the most common IA failures.
37
+
38
+ **Types of labels:**
39
+ - Contextual links — hyperlinked text within content ("Learn more about pricing")
40
+ - Headings — section and page titles that establish hierarchy
41
+ - Navigation labels — menu items that represent categories or destinations
42
+ - Index terms — keywords, tags, and metadata used for search and filtering
43
+
44
+ **Labeling principles:**
45
+ - Use language your users use, not internal jargon or departmental terminology
46
+ - Be consistent — if one section says "Help," do not label the equivalent elsewhere as "Support," "FAQ," and "Resources"
47
+ - Be specific — "Services" is vague; "Cloud Hosting Plans" is actionable
48
+ - Front-load labels with the most meaningful word (users scan the first 2-3 words)
49
+ - Test labels with real users via tree testing and first-click studies
50
+
51
+ ### 1.3 Navigation Systems
52
+
53
+ Navigation systems help users move through information space, understand where they are, and know what is available.
54
+
55
+ **Embedded Navigation (integrated into pages):**
56
+
57
+ | System | Purpose | Typical Implementation |
58
+ |--------|---------|----------------------|
59
+ | Global navigation | Persistent site-wide access to top-level sections | Top nav bar, hamburger menu |
60
+ | Local navigation | Section-specific navigation within a subsection | Sidebar, section tabs |
61
+ | Contextual navigation | In-content links to related items | "Related articles," inline links |
62
+ | Breadcrumbs | Show current position in hierarchy | Location-based trail (Home > Category > Page) |
63
+
64
+ **Supplemental Navigation (exist outside page content):**
65
+
66
+ | System | Purpose | Typical Implementation |
67
+ |--------|---------|----------------------|
68
+ | Site map | Complete overview of site structure | HTML page listing all sections |
69
+ | Site index | Alphabetical listing of topics | A-Z index page |
70
+ | Guides/wizards | Task-oriented sequential navigation | Step-by-step flows |
71
+ | Faceted navigation | Multi-dimensional filtering | Filter panels on search/browse pages |
72
+ | Footer navigation | Secondary access to key pages | Fat footer with categorized links |
73
+ | Utility navigation | Access to account, settings, help | Top-right corner links |
74
+
75
+ **Navigation design principles (per Rosenfeld/Morville):**
76
+ - Provide context — users must know where they are, where they have been, and where they can go
77
+ - Maintain consistency — global navigation should not change structure or position across pages
78
+ - Support multiple pathways — different users find information differently; offer hierarchy, search, and cross-links
79
+ - Offer escape hatches — users should always be able to get back to known ground (home, up one level)
80
+ - Limit choices per level — Miller's Law suggests 7 plus or minus 2 items; in practice, 5-9 primary navigation items perform best
81
+
82
+ ### 1.4 Search Systems
83
+
84
+ Search systems complement navigation for large or complex information spaces. IA governs what is searchable, how results are organized, and what refinement is available.
85
+
86
+ **Search system components:**
87
+ - Search interface — input field, auto-suggest, advanced search options
88
+ - Search engine/algorithm — indexing, relevance ranking, weighting
89
+ - Search results — display format, snippets, metadata, pagination
90
+ - Search refinement — filters, facets, sorting, "did you mean" corrections
91
+ - Search zones — ability to scope search to a section, content type, or date range
92
+
93
+ **When search is critical:**
94
+ - Sites with more than 100-200 content items
95
+ - Users who arrive with a specific known-item need
96
+ - Content that does not fit neatly into a single hierarchical path
97
+ - E-commerce, documentation, knowledge bases, intranets
98
+
99
+ **Search strategy decisions:**
100
+ - What content gets indexed (and what gets excluded)
101
+ - How synonyms and related terms are handled (controlled vocabulary, thesaurus)
102
+ - What metadata is surfaced in results (dates, authors, content types)
103
+ - How "no results" states are handled (suggestions, popular content, help)
104
+ - Whether federated search across multiple repositories is needed
105
+
106
+ ---
107
+
108
+ ## 2. Core Methods & Frameworks
109
+
110
+ ### 2.1 Card Sorting
111
+
112
+ Card sorting reveals how users naturally group and categorize information. It is the primary generative method for discovering user mental models.
113
+
114
+ **Open Card Sort:**
115
+ - Participants receive 30-60 content items on individual cards
116
+ - They create their own groups and name the categories
117
+ - Best for: early-stage IA design, discovering user mental models, generating category ideas
118
+ - Sample size: 15-30 participants yields reliable patterns (NNG)
119
+ - Analysis: similarity matrix, dendrogram (cluster analysis), category frequency
120
+
121
+ **Closed Card Sort:**
122
+ - Participants sort cards into predefined categories
123
+ - Best for: validating an existing or proposed IA structure
124
+ - Reveals: which categories are clear, which are confusing, where items lack a natural home
125
+ - Sample size: 15-30 participants
126
+
127
+ **Hybrid Card Sort:**
128
+ - Participants sort into predefined categories but can also create new ones
129
+ - Best for: refining a draft IA — validates what works while revealing gaps
130
+ - Combines generative and evaluative insights
131
+
132
+ **Card sorting best practices (per NNG and Optimal Workshop):**
133
+ - Write card labels using language from actual content (page titles, feature names)
134
+ - Avoid cards with overlapping keywords — users cluster by shared words, not meaning
135
+ - Include 30-70 cards; fewer than 20 provides insufficient data, more than 70 causes fatigue
136
+ - Capture think-aloud data in moderated sessions for qualitative insight
137
+ - Run remote unmoderated sorts for larger sample sizes
138
+ - Analyze with both quantitative (similarity matrices) and qualitative (participant comments) methods
139
+ - Do not treat results as prescriptive — card sorting informs IA decisions, it does not make them
140
+
141
+ ### 2.2 Tree Testing
142
+
143
+ Tree testing (also called "reverse card sorting") evaluates an existing or proposed IA by asking users to find items in a text-only hierarchy — no visual design, no navigation aids.
144
+
145
+ **Process:**
146
+ 1. Create a text-based tree representing your IA hierarchy
147
+ 2. Write 8-10 task scenarios ("Where would you find information about returning a product?")
148
+ 3. Participants navigate the tree to find the correct location
149
+ 4. Measure: success rate, directness (found it without backtracking), time to complete
150
+
151
+ **Key metrics:**
152
+ - Task success rate — percentage of participants who found the correct answer
153
+ - Directness — percentage who navigated directly without backtracking (indicates confidence)
154
+ - Time on task — longer times suggest labeling or structure confusion
155
+ - First click correctness — if the first click is correct, overall success rate is significantly higher
156
+
157
+ **Tree testing best practices:**
158
+ - Test with 50+ participants for statistically reliable results
159
+ - Keep sessions under 15-20 minutes (fewer than 10 tasks)
160
+ - Randomize task order to eliminate learning effects
161
+ - Test competitor or alternative structures for comparison
162
+ - Run tree testing after card sorting to validate the IA generated from card sort insights
163
+
164
+ **Combined workflow (recommended by NNG):**
165
+ 1. Open card sort to discover mental models
166
+ 2. Draft IA structure from card sort results
167
+ 3. Tree test the draft IA to evaluate findability
168
+ 4. Iterate on labels and structure based on results
169
+ 5. Re-test until success rates meet targets (aim for 80%+ task success)
170
+
171
+ ### 2.3 Site Maps
172
+
173
+ A site map is a visual representation of the IA hierarchy showing all pages, sections, and their relationships.
174
+
175
+ **Types:**
176
+ - Hierarchical site map — tree diagram showing parent-child relationships
177
+ - Flat site map — list format, often used for XML sitemaps (SEO)
178
+ - Visual site map — diagrammatic with annotations for page types, templates, and content models
179
+
180
+ **Creating effective site maps:**
181
+ - Start from the top level and work down; limit depth to 3-4 levels where possible
182
+ - Use consistent visual conventions (boxes for pages, lines for relationships, color for page types)
183
+ - Annotate with page templates, content types, and dynamic behavior
184
+ - Include cross-links and polyhierarchy where items appear in multiple locations
185
+ - Version and date site maps — they are living documents that evolve with the product
186
+
187
+ ### 2.4 User Flows
188
+
189
+ User flows map the paths users take to accomplish specific tasks through the information architecture.
190
+
191
+ **Components:**
192
+ - Entry points — where users begin (homepage, search engine, deep link, notification)
193
+ - Decision points — where users make choices (navigation clicks, search queries, filter selections)
194
+ - Pages/screens — the content they encounter along the way
195
+ - Exit points — task completion, abandonment, or redirection
196
+
197
+ **User flow best practices:**
198
+ - Map flows for the top 5-10 critical user tasks
199
+ - Include both the "happy path" and common alternative paths
200
+ - Identify dead ends, loops, and unnecessary steps
201
+ - Validate flows against analytics data (actual user behavior vs. intended paths)
202
+ - Use flows to identify where the IA creates friction or forces unnecessary navigation
203
+
204
+ ### 2.5 Content Inventory and Audit
205
+
206
+ A content inventory catalogs every piece of content in an existing system. A content audit evaluates the quality, accuracy, and relevance of that content.
207
+
208
+ **Content Inventory — what to capture per item:**
209
+ URL/location, page title, content type, owner/author, last updated date, word count, metadata (tags/categories/keywords), traffic/usage data, status (active/outdated/duplicate/orphaned), and current IA location.
210
+
211
+ **Content Audit — evaluation criteria:**
212
+ - Accuracy — is the information still correct?
213
+ - Relevance — does the audience still need this content?
214
+ - Completeness — are there gaps in coverage?
215
+ - Consistency — does it follow current style, tone, and terminology?
216
+ - Findability — can users reach this content through navigation and search?
217
+ - ROT analysis — identify content that is Redundant, Outdated, or Trivial
218
+
219
+ **Conducting the audit:** Export a full inventory via crawler (Screaming Frog, Sitebulb) or CMS export. Enrich with analytics data to identify high-traffic and zero-traffic pages. Categorize by type, topic, audience, and lifecycle stage. Score each item on accuracy, relevance, and quality. Make disposition decisions (keep, update, merge, archive, delete). Use findings to inform the new IA.
220
+
221
+ ### 2.6 Mental Model Alignment
222
+
223
+ A mental model is a user's internal representation of how they expect information to be organized. IA succeeds when it matches these expectations; it fails when it imposes structures that conflict with user cognition.
224
+
225
+ **Methods for discovering mental models:**
226
+ - Open card sorting — reveals natural grouping patterns
227
+ - User interviews — ask users to describe how they think about a topic domain
228
+ - Diary studies — observe how users naturally seek and organize information over time
229
+ - Search log analysis — actual queries reveal the language and categories users expect
230
+ - Competitor analysis — observe IA patterns users are already accustomed to
231
+ - Mental model diagrams (per Indi Young) — map user behaviors, thoughts, and feelings to content and features
232
+
233
+ **Alignment strategies:**
234
+ - Match top-level categories to the user's task or topic model, not the organization's departmental structure
235
+ - Use the same vocabulary users use (discovered through research, search logs, and support tickets)
236
+ - Provide multiple pathways when user mental models diverge (some users think by topic, others by task)
237
+ - Use polyhierarchy to place items where multiple mental models expect them
238
+ - Test alignment continuously — mental models shift as users gain expertise and as the product evolves
239
+
240
+ ### 2.7 Taxonomies and Controlled Vocabularies
241
+
242
+ Taxonomies provide standardized classification systems. Controlled vocabularies ensure consistent labeling across content, navigation, and search.
243
+
244
+ **Taxonomy types:**
245
+ - Flat taxonomy — a single list of terms with no hierarchy (tags)
246
+ - Hierarchical taxonomy — terms arranged in parent-child relationships (categories > subcategories)
247
+ - Faceted taxonomy — multiple independent dimensions for classifying the same content (topic, format, audience, date)
248
+ - Network taxonomy — terms connected through associative relationships (related terms, see-also references)
249
+
250
+ **Controlled vocabulary components:**
251
+ - Preferred terms — the canonical label for a concept
252
+ - Synonyms/variants — alternative terms that map to the preferred term ("cell phone" maps to "mobile phone")
253
+ - Broader terms (BT) — parent concepts
254
+ - Narrower terms (NT) — child concepts
255
+ - Related terms (RT) — associated concepts that are not hierarchically related
256
+ - Scope notes — definitions clarifying when and how to apply a term
257
+
258
+ **Building a taxonomy:**
259
+ 1. Gather existing classification schemes from the CMS, content, and stakeholders
260
+ 2. Analyze search logs for user language patterns
261
+ 3. Conduct open card sorts to surface user-generated categories
262
+ 4. Draft the taxonomy with preferred terms, synonyms, and hierarchy
263
+ 5. Validate with subject matter experts (SMEs) for domain accuracy
264
+ 6. Test with tree testing and closed card sorts for user comprehension
265
+ 7. Document governance rules — who can add, modify, or deprecate terms
266
+ 8. Plan for maintenance — taxonomies require ongoing curation as content evolves
267
+
268
+ ### 2.8 IA Heuristics
269
+
270
+ Abby Covert synthesized five historical sources of IA evaluation criteria into ten heuristic principles. These provide a structured framework for evaluating any information architecture:
271
+
272
+ **Covert's Ten IA Heuristics:**
273
+
274
+ | Heuristic | Evaluation Question |
275
+ |-----------|-------------------|
276
+ | Findable | Can users locate the information they need? |
277
+ | Accessible | Can all users access the content regardless of ability or device? |
278
+ | Clear | Is the meaning of labels, categories, and structures unambiguous? |
279
+ | Communicative | Does the IA convey the scope, purpose, and structure of the content? |
280
+ | Useful | Does the structure help users accomplish their goals? |
281
+ | Credible | Does the organization of information inspire trust and confidence? |
282
+ | Controllable | Can users navigate, filter, and customize their experience? |
283
+ | Valuable | Does the IA deliver value to both users and the organization? |
284
+ | Learnable | Can users build a mental model of the structure and predict where things are? |
285
+ | Delightful | Does the IA create a pleasant, satisfying experience of finding information? |
286
+
287
+ **Dan Brown's Eight Principles of IA:**
288
+
289
+ | Principle | Description |
290
+ |-----------|-------------|
291
+ | Objects | Treat content as a living thing with a lifecycle, behaviors, and attributes |
292
+ | Choices | Present meaningful choices focused on a particular task; avoid overwhelming users |
293
+ | Disclosure | Reveal just enough information to help users anticipate what they will find next |
294
+ | Exemplars | Show examples of category contents to clarify ambiguous labels |
295
+ | Front Doors | Assume users enter from any page, not just the homepage; every page must provide context |
296
+ | Multiple Classifications | Offer several ways to browse the same content (topic, task, audience) |
297
+ | Focused Navigation | Keep each navigation scheme focused on one organizing principle; do not mix metaphors |
298
+ | Growth | Design the IA to accommodate future content without structural rework |
299
+
300
+ ---
301
+
302
+ ## 3. Deliverables
303
+
304
+ ### 3.1 Site Maps
305
+
306
+ **Description:** Visual diagrams showing the hierarchical structure of all pages, sections, and their relationships.
307
+
308
+ **Quality criteria:**
309
+ - Covers all content areas — no orphaned sections
310
+ - Clearly indicates hierarchy depth (aim for 3-4 levels maximum)
311
+ - Distinguishes page types visually (landing pages, detail pages, utility pages, forms)
312
+ - Annotates dynamic content areas (search results, filtered views, user-generated content)
313
+ - Shows cross-links and polyhierarchy where items appear in multiple locations
314
+ - Includes a legend explaining visual conventions
315
+ - Is versioned and dated for change tracking
316
+ - Has been validated through tree testing with representative users
317
+
318
+ ### 3.2 Navigation Structures
319
+
320
+ **Description:** Specifications for all navigation systems — global, local, contextual, supplemental — including labels, hierarchy, and behavior.
321
+
322
+ **Quality criteria:**
323
+ - Global navigation limited to 5-9 top-level items
324
+ - Labels tested with users (via tree testing or preference testing)
325
+ - Responsive behavior specified (how navigation adapts on mobile, tablet, desktop)
326
+ - States defined (default, hover, active, current, disabled)
327
+ - Mega-menu content specified where applicable (groupings, featured items, CTAs)
328
+ - Local navigation defined for each major section
329
+ - Breadcrumb logic documented (what appears at each level)
330
+ - Utility navigation items identified (search, account, language, help)
331
+
332
+ ### 3.3 Content Models
333
+
334
+ **Description:** Definitions of content types, their attributes, relationships, and display rules.
335
+
336
+ **Quality criteria:**
337
+ - Every content type has a defined schema (title, body, metadata fields, relationships)
338
+ - Relationships between content types are explicit (article has-many tags, product belongs-to category)
339
+ - Required vs. optional fields are specified
340
+ - Character limits and formatting rules are documented
341
+ - Content lifecycle states are defined (draft, review, published, archived)
342
+ - Reuse patterns are identified (shared components, content blocks, snippets)
343
+ - Model supports the taxonomy and classification scheme
344
+ - Validated against actual content during audit
345
+
346
+ ### 3.4 Taxonomies
347
+
348
+ **Description:** The complete classification system with all terms, relationships, synonyms, and governance rules.
349
+
350
+ **Quality criteria:**
351
+ - Terms are user-tested and align with user vocabulary (not internal jargon)
352
+ - Hierarchy depth is manageable (3-4 levels maximum)
353
+ - Each term has a scope note defining its meaning and usage
354
+ - Synonyms and variant terms are mapped to preferred terms
355
+ - Governance process is documented (who adds, modifies, deprecates terms)
356
+ - Taxonomy is faceted where content needs multiple classification dimensions
357
+ - Cross-references (related terms) are defined where helpful
358
+ - Growth plan accounts for new content areas
359
+
360
+ ### 3.5 User Flow Diagrams
361
+
362
+ **Description:** Visual maps of the paths users take to accomplish key tasks through the IA.
363
+
364
+ **Quality criteria:**
365
+ - Cover the top 5-10 critical user tasks
366
+ - Include entry points from all major channels (search engine, direct, referral, notification)
367
+ - Show decision points with branching logic
368
+ - Identify error states and recovery paths
369
+ - Mark the "happy path" distinctly from alternative paths
370
+ - Note where analytics data validates or contradicts the intended flow
371
+ - Include estimated completion time and step count
372
+ - Have been validated against usability testing observations
373
+
374
+ ### 3.6 Content Inventory Spreadsheet
375
+
376
+ **Description:** Complete catalog of all existing content with metadata and audit scores.
377
+
378
+ **Quality criteria:**
379
+ - Every page/content item is included (no gaps)
380
+ - Metadata fields are consistently populated
381
+ - Audit scores are applied using consistent criteria
382
+ - Disposition recommendations are provided for every item (keep, update, merge, archive, delete)
383
+ - Analytics data (traffic, engagement) is integrated
384
+ - Owner/stakeholder is assigned for each content area
385
+ - Document is maintained as a living artifact through the redesign process
386
+
387
+ ---
388
+
389
+ ## 4. Tools & Techniques
390
+
391
+ ### 4.1 Optimal Workshop — Card Sorting & Tree Testing
392
+
393
+ **OptimalSort (card sorting):**
394
+ - Supports open, closed, and hybrid card sorts
395
+ - Remote unmoderated sessions scale to hundreds of participants
396
+ - Built-in analysis: similarity matrix, dendrogram, participant-centric analysis
397
+ - Standardization grid shows how consistently participants placed each card
398
+ - Export raw data for custom analysis
399
+
400
+ **Treejack (tree testing):**
401
+ - Upload a text-based hierarchy to test findability
402
+ - Measures success rate, directness, and time-on-task per task
403
+ - Pietree visualization shows where users go right and wrong at each node
404
+ - First-click analysis reveals whether users start on the correct path
405
+ - Compare multiple tree structures side by side
406
+
407
+ **Other Optimal Workshop tools relevant to IA:**
408
+ - Chalkmark — first-click testing on wireframes or mockups
409
+ - Reframer — qualitative research analysis and tagging
410
+ - Questions — survey tool integrated with IA research
411
+
412
+ ### 4.2 Miro & FigJam — Visual Mapping
413
+
414
+ **Use for:**
415
+ - Collaborative site map creation during workshops
416
+ - Affinity mapping of card sort results
417
+ - User flow diagramming with stakeholder participation
418
+ - Content model visualization
419
+ - IA workshop facilitation (remote and in-person)
420
+
421
+ **Best practices:**
422
+ - Use templates and component libraries for consistent site map notation
423
+ - Color-code by content type, template, or section owner
424
+ - Use frames to organize different IA views (current state vs. proposed)
425
+ - Add sticky notes for annotations, questions, and decisions
426
+ - Export to PDF for stakeholder review and documentation
427
+
428
+ ### 4.3 Spreadsheets — Content Inventory
429
+
430
+ **Google Sheets / Excel / Airtable for:**
431
+ - Content inventory and audit tracking
432
+ - Taxonomy management and term definitions
433
+ - Metadata schema documentation
434
+ - URL mapping (old URL to new URL for redirects)
435
+ - Navigation specification tables
436
+
437
+ **Spreadsheet structure for content inventory:**
438
+ ```
439
+ | ID | URL | Title | Content Type | Section | Owner | Last Updated | Traffic | Audit Score | Disposition |
440
+ ```
441
+
442
+ **Tips:**
443
+ - Use data validation for content type and disposition columns (consistency)
444
+ - Create pivot tables to summarize content by type, section, and disposition
445
+ - Use conditional formatting to highlight outdated or orphaned content
446
+ - Maintain a separate sheet for the taxonomy with term definitions
447
+ - Use Airtable for relational data (linking content items to taxonomy terms, owners, and templates)
448
+
449
+ ### 4.4 Diagramming Tools
450
+
451
+ **Draw.io (diagrams.net) / Lucidchart / OmniGraffle:**
452
+ - Formal site map creation with professional notation
453
+ - User flow diagrams with standardized shapes (Jesse James Garrett's visual vocabulary)
454
+ - Content model entity-relationship diagrams
455
+ - Navigation structure specifications
456
+
457
+ **Standard visual vocabulary:** Rectangle (page), diamond (decision point), circle (entry/exit), rounded rectangle (action), dashed line (conditional), solid line (required path). Use color coding for content type, template, or status.
458
+
459
+ ### 4.5 Analytics Tools for IA Research
460
+
461
+ **Google Analytics / Matomo / Amplitude** — Use navigation summaries, site search reports (top queries, zero-result queries, query reformulations), behavior flows, and landing/exit page analysis to validate IA against actual user behavior. Search logs are especially valuable: top queries reveal what users expect to find, zero-result queries reveal content or vocabulary gaps, and reformulations indicate labeling confusion.
462
+
463
+ ### 4.6 Prototyping for IA Validation
464
+
465
+ **Axure / Figma / Sketch** — Build interactive navigation prototypes for usability testing, click-through site maps for stakeholder review, and responsive navigation behavior validation.
466
+
467
+ ---
468
+
469
+ ## 5. Common Failures
470
+
471
+ ### 5.1 Organizing by Organizational Structure, Not User Mental Models
472
+
473
+ **The problem:** The IA mirrors the company's org chart — "Marketing," "Engineering," "Human Resources" — rather than reflecting how users think about the content. Each department demands its own section in the navigation.
474
+
475
+ **Why it happens:** Internal politics, stakeholder demands, path of least resistance during design.
476
+
477
+ **The fix:**
478
+ - Conduct card sorting with external users to discover their mental models
479
+ - Present user research data to stakeholders as evidence for user-centered structure
480
+ - Map departmental content to user-centered categories (departments own content but do not own navigation labels)
481
+ - Use audience-based or task-based top-level navigation instead of department-based
482
+
483
+ **NNG guidance:** "Clumsy org-chart sites arranged solely by how the organization is managed are much less amusing to users who cannot find what they are looking for because they do not understand — or care — how your management is organized."
484
+
485
+ ### 5.2 Hierarchy Too Deep
486
+
487
+ **The problem:** Users must click through 5, 6, or more levels to reach content. Each click increases cognitive load and the risk of abandonment.
488
+
489
+ **Why it happens:** Over-categorization, desire for "neat" structures, failure to consider user patience.
490
+
491
+ **The fix:**
492
+ - Aim for no more than 3-4 levels of depth for most content
493
+ - Prefer wider (more items per level) over deeper (more levels) structures
494
+ - Use cross-links and contextual navigation to provide shortcuts to deep content
495
+ - Implement breadcrumbs to help users recover from deep navigation
496
+ - Use faceted navigation as an alternative to deep hierarchies for filterable content
497
+ - Monitor analytics for drop-off at each navigation level
498
+
499
+ **NNG guidance:** "Requiring users to click through many levels to get to specific content usually does not work well, as users easily become lost, distracted, or simply decide it is too much work and give up."
500
+
501
+ ### 5.3 Inconsistent Labeling
502
+
503
+ **The problem:** The same concept is labeled differently across the site — "Help" in the header, "Support" in the footer, "FAQ" on a landing page, "Knowledge Base" in search. Users cannot build a reliable mental model.
504
+
505
+ **Why it happens:** Different teams create content independently, no terminology governance, no labeling standards documented.
506
+
507
+ **The fix:**
508
+ - Create a controlled vocabulary with preferred terms and documented synonyms
509
+ - Audit all navigation labels, page titles, and CTAs for consistency
510
+ - Establish labeling guidelines in the content style guide
511
+ - Assign taxonomy governance to a specific role or team
512
+ - Use search synonyms to handle user vocabulary variations without UI inconsistency
513
+
514
+ ### 5.4 No Search Strategy
515
+
516
+ **The problem:** Search is treated as a feature to "just add" rather than a system to design. Results are irrelevant, filters are missing, zero-result pages offer no help, and the search index includes outdated content.
517
+
518
+ **Why it happens:** Search is often considered a technical feature rather than an IA concern. No one owns the search experience end-to-end.
519
+
520
+ **The fix:**
521
+ - Define what gets indexed and what does not (exclude outdated, duplicate, or administrative content)
522
+ - Implement a synonym/thesaurus layer so user vocabulary maps to content vocabulary
523
+ - Design the zero-results state with suggestions, popular content, and help options
524
+ - Add faceted filtering for search results (content type, date, section, topic)
525
+ - Analyze search logs regularly to identify gaps, failed queries, and vocabulary mismatches
526
+ - Treat search as a navigation system that requires the same IA rigor as the main navigation
527
+
528
+ ### 5.5 Jargon in Navigation
529
+
530
+ **The problem:** Navigation labels use internal terminology, industry jargon, or product names that users do not understand. "Synergy Solutions" means nothing to a user looking for "Consulting Services."
531
+
532
+ **Why it happens:** Subject matter experts write labels using their own vocabulary. Marketing insists on branded terminology. No user testing of labels.
533
+
534
+ **The fix:**
535
+ - Test all navigation labels with representative users via tree testing
536
+ - Use search log analysis to discover the language users actually use
537
+ - Replace branded or jargon terms with plain language in navigation (use branded terms on landing pages instead)
538
+ - Apply the front-loading principle — put the most meaningful, recognizable word first in every label
539
+ - When domain-specific terms are necessary, provide contextual help (tooltips, descriptions)
540
+
541
+ ### 5.6 Flat Swamp — No Organizing Principle
542
+
543
+ **The problem:** Content is treated as a flat collection of individual items with no grouping, hierarchy, or relationship structure. Every page is equally accessible (or inaccessible) from every other page.
544
+
545
+ **Why it happens:** Content grows organically without planning. CMS allows creation without requiring classification. No IA governance.
546
+
547
+ **The fix:**
548
+ - Conduct a content audit to identify themes, types, and natural groupings
549
+ - Build a taxonomy retroactively and apply it to all existing content
550
+ - Create section landing pages that curate and organize related content
551
+ - Implement related-content links based on taxonomy relationships
552
+ - Establish content governance requiring classification at time of creation
553
+
554
+ ### 5.7 Neglecting Mobile IA
555
+
556
+ **The problem:** The IA was designed for desktop with 8-10 top-level navigation items, mega-menus, and sidebar navigation. On mobile, it collapses into an unusable hamburger menu with deeply nested levels.
557
+
558
+ **Why it happens:** IA designed before responsive considerations. Desktop-first mindset.
559
+
560
+ **The fix:**
561
+ - Design IA mobile-first — if it works on a small screen, it will work on a large one
562
+ - Prioritize navigation items for mobile (not everything needs to be in the hamburger menu)
563
+ - Use progressive disclosure — show top-level categories first, reveal sub-levels on interaction
564
+ - Consider bottom navigation for the 3-5 most critical sections on mobile
565
+ - Test navigation on actual mobile devices, not just responsive browser simulations
566
+
567
+ ### 5.8 Orphaned Content
568
+
569
+ **The problem:** Pages exist in the CMS but are not linked from any navigation, category page, or related-content module. Users cannot find them through browsing; they are only accessible via direct URL or search (if indexed).
570
+
571
+ **Why it happens:** Content is created and published without being placed in the IA. Navigation updates lag behind content creation. Redesigns leave old pages stranded.
572
+
573
+ **The fix:**
574
+ - Run regular crawls to identify orphaned pages (Screaming Frog, Sitebulb)
575
+ - Require content creators to specify IA placement when publishing
576
+ - Include orphaned-page checks in content governance processes
577
+ - Either integrate orphaned content into the IA or remove/redirect it
578
+
579
+ ---
580
+
581
+ ## 6. Integration with Development
582
+
583
+ ### 6.1 URL Structure
584
+
585
+ The IA should directly inform the URL structure. URLs are a user-facing representation of information hierarchy.
586
+
587
+ **Principles:**
588
+ - URLs should reflect the IA hierarchy: `/category/subcategory/item-name`
589
+ - Use human-readable slugs, not IDs or query parameters: `/products/wireless-headphones` not `/products?id=4829`
590
+ - Keep URLs as short as possible while remaining descriptive
591
+ - Use hyphens, not underscores, to separate words (Google treats hyphens as word separators)
592
+ - Maintain URL consistency — changing URLs breaks bookmarks, shared links, and SEO equity
593
+ - Plan a redirect strategy (301 redirects) for any URL changes during IA restructuring
594
+
595
+ **URL structure anti-patterns:**
596
+ - URLs that expose database structure: `/node/12847`
597
+ - URLs that repeat the domain in the path: `/company-name/company-name-products/`
598
+ - Overly deep URLs: `/a/b/c/d/e/f/page.html` (signals IA depth problems)
599
+ - Parameter-heavy URLs: `/search?cat=3&sub=7&type=2&sort=date`
600
+ - Mixed conventions: `/Products/my_category/item-name` (case and separator inconsistency)
601
+
602
+ ### 6.2 Routing Architecture
603
+
604
+ The IA informs application routing in single-page applications (SPAs) and server-rendered applications.
605
+
606
+ **Framework routing should mirror IA:**
607
+ ```
608
+ / → Home
609
+ /products → Product category listing
610
+ /products/:category → Product subcategory
611
+ /products/:category/:slug → Product detail
612
+ /about → About section
613
+ /about/team → Team page
614
+ /help → Help center
615
+ /help/:topic → Help topic
616
+ /help/:topic/:article → Help article
617
+ ```
618
+
619
+ **Development considerations:**
620
+ - Route parameters should match IA concepts (category, topic, article) not database concepts (id, type)
621
+ - Nested routes should reflect IA hierarchy for correct breadcrumb generation
622
+ - Dynamic routes must handle invalid paths gracefully (404 pages with navigation, not dead ends)
623
+ - Consider route-based code splitting aligned with IA sections for performance
624
+ - API endpoint structure should parallel the IA for developer consistency
625
+
626
+ ### 6.3 Breadcrumb Implementation
627
+
628
+ Breadcrumbs are a direct expression of the IA hierarchy in the UI. Implementation must align with the defined IA structure.
629
+
630
+ **Types of breadcrumbs:**
631
+ - Location-based — shows position in hierarchy (Home > Electronics > Headphones > Wireless)
632
+ - Attribute-based — shows applied filters (Electronics > Brand: Sony > Price: Under $100)
633
+ - Path-based — shows the user's actual navigation history (generally not recommended — browser back button serves this purpose)
634
+
635
+ **Implementation requirements:**
636
+ - Breadcrumbs must reflect the canonical IA location, not the user's navigation path
637
+ - Items in the breadcrumb should be clickable links (except the current page)
638
+ - The current page should be visually distinct (text only, not a link)
639
+ - Use `aria-label="Breadcrumb"` and `<nav>` element for accessibility
640
+ - Implement BreadcrumbList structured data (schema.org) for SEO
641
+
642
+ **Structured data example:**
643
+ ```json
644
+ {
645
+ "@context": "https://schema.org",
646
+ "@type": "BreadcrumbList",
647
+ "itemListElement": [
648
+ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
649
+ { "@type": "ListItem", "position": 2, "name": "Electronics", "item": "https://example.com/electronics" },
650
+ { "@type": "ListItem", "position": 3, "name": "Headphones", "item": "https://example.com/electronics/headphones" }
651
+ ]
652
+ }
653
+ ```
654
+
655
+ ### 6.4 SEO Implications
656
+
657
+ IA has direct and significant impact on search engine optimization. Search engines use site structure to understand content relationships and assign authority.
658
+
659
+ **IA and SEO alignment:**
660
+
661
+ | IA Element | SEO Impact |
662
+ |------------|-----------|
663
+ | Hierarchy depth | Pages closer to the root receive more link equity (crawl depth) |
664
+ | Internal linking | Links between related content distribute authority and signal relationships |
665
+ | URL structure | Clean, descriptive URLs improve click-through rates in search results |
666
+ | Breadcrumbs | BreadcrumbList schema enhances search result appearance with site hierarchy |
667
+ | Navigation labels | Navigation text serves as anchor text for internal links — use descriptive labels |
668
+ | Taxonomy/tags | Taxonomy pages can rank for category-level keywords |
669
+ | Duplicate content | Poor IA with content in multiple locations creates canonicalization issues |
670
+ | Site maps | XML sitemaps (distinct from HTML sitemaps) help search engines discover all pages |
671
+ | Orphaned pages | Pages with no internal links are difficult for search engines to discover and rank |
672
+
673
+ **Technical SEO considerations from IA:**
674
+ - Implement canonical URLs when content legitimately appears at multiple IA locations
675
+ - Use `rel="nofollow"` on faceted navigation links to prevent search engine crawl traps
676
+ - Ensure the IA allows search engines to reach any page within 3 clicks from the homepage
677
+ - Create hub pages for each major taxonomy category — these become keyword-targeting assets
678
+ - Plan 301 redirects for any URL changes to preserve search equity
679
+ - Monitor crawl stats in Google Search Console to verify search engines can traverse the IA
680
+
681
+ ### 6.5 State Management & Navigation State
682
+
683
+ - Derive active/current navigation states from the current route, not separate state stores
684
+ - Compute breadcrumb data from route metadata, not hardcoded per page
685
+ - Support deep linking — users must be able to bookmark and share any IA location
686
+ - Reflect filter and facet states in the URL for shareability
687
+ - Ensure browser history (back/forward) works correctly with all navigation interactions
688
+
689
+ ### 6.6 Accessibility in Navigation
690
+
691
+ - Wrap navigation in `<nav>` with `aria-label` distinguishing multiple nav regions
692
+ - Provide "Skip to main content" link as the first focusable element
693
+ - Use `aria-current="page"` on the active navigation item
694
+ - Use `aria-expanded` and `aria-haspopup` on expandable menus with full keyboard support
695
+ - Wrap breadcrumbs in `<nav aria-label="Breadcrumb">` using `<ol>` with `aria-current="page"` on the last item
696
+ - Manage focus on SPA page transitions — move focus to the new content area
697
+
698
+ ---
699
+
700
+ ## 7. Foundational References
701
+
702
+ ### Key Texts
703
+
704
+ - **Rosenfeld, Morville, & Arango** — *Information Architecture: For the Web and Beyond* (4th ed., O'Reilly, 2015). The definitive text ("the polar bear book"). Defines the four systems and provides comprehensive methodology.
705
+ - **Abby Covert** — *How to Make Sense of Any Mess* (2014). Accessible introduction to IA thinking and the concept of intentional structure.
706
+ - **Dan Brown** — *Practical Design Discovery* and the Eight Principles of IA (objects, choices, disclosure, exemplars, front doors, multiple classifications, focused navigation, growth).
707
+ - **Andrea Resmini & Luca Rosati** — *Pervasive Information Architecture* (2011). Extends IA to cross-channel and physical-digital environments.
708
+ - **Indi Young** — *Mental Models* (2008). Methodology for understanding and aligning to user mental models.
709
+
710
+ ### Key Organizations and Resources
711
+
712
+ - **Nielsen Norman Group (NNG)** — Research-based articles on IA, navigation, card sorting, tree testing. Top 10 IA Mistakes is essential reading.
713
+ - **Information Architecture Institute** — Professional community for IA practitioners.
714
+ - **Abby Covert's IA Heuristics** — Ten-principle evaluation framework from five historical sources.
715
+ - **Optimal Workshop** — Primary tool for card sorting (OptimalSort) and tree testing (Treejack).
716
+
717
+ ---
718
+
719
+ ## 8. Quick Reference Checklist
720
+
721
+ Use this checklist to evaluate and validate an information architecture. Each item should be verifiable through research, testing, or documentation review.
722
+
723
+ ### Research & Discovery
724
+
725
+ - [ ] User mental models have been researched (card sorting, interviews, search log analysis)
726
+ - [ ] Content inventory has been completed and audited (ROT analysis done)
727
+ - [ ] Competitor/analogous IA has been analyzed for patterns and conventions
728
+ - [ ] Key user tasks have been identified and prioritized (top 5-10)
729
+ - [ ] User vocabulary has been documented from research, search logs, and support data
730
+ - [ ] Stakeholder requirements and constraints have been gathered
731
+
732
+ ### Structure & Organization
733
+
734
+ - [ ] Top-level categories reflect user mental models, not org structure
735
+ - [ ] Hierarchy depth does not exceed 3-4 levels for most content
736
+ - [ ] Every content item has a clear, logical home in the hierarchy
737
+ - [ ] Polyhierarchy is used where items genuinely belong in multiple categories
738
+ - [ ] Content types are defined with clear schemas and relationships
739
+ - [ ] Growth has been planned for — structure accommodates future content without rework
740
+
741
+ ### Labeling & Vocabulary
742
+
743
+ - [ ] Navigation labels have been tested with users (tree testing, preference testing)
744
+ - [ ] Labels use user language, not internal jargon or branded terminology
745
+ - [ ] Labels are consistent across all navigation systems (global, local, footer, breadcrumbs)
746
+ - [ ] A controlled vocabulary or taxonomy has been defined and documented
747
+ - [ ] Synonyms are mapped so search handles vocabulary variations
748
+ - [ ] Labels are front-loaded with the most meaningful word
749
+
750
+ ### Navigation Systems
751
+
752
+ - [ ] Global navigation is limited to 5-9 items and is consistent across all pages
753
+ - [ ] Local navigation is defined for each major section
754
+ - [ ] Breadcrumbs are implemented and reflect the IA hierarchy correctly
755
+ - [ ] Contextual navigation (related content) connects items across sections
756
+ - [ ] Mobile navigation has been designed and tested (not just a collapsed desktop nav)
757
+ - [ ] Utility navigation (search, account, help) is consistently placed
758
+ - [ ] Footer provides secondary access to key pages and sections
759
+
760
+ ### Search
761
+
762
+ - [ ] Search scope and indexed content have been defined
763
+ - [ ] Zero-results state provides helpful alternatives (suggestions, popular content)
764
+ - [ ] Search results include relevant metadata (content type, date, section)
765
+ - [ ] Faceted filtering is available for content-rich search results
766
+ - [ ] Synonym handling is implemented (thesaurus or equivalent)
767
+ - [ ] Search logs are monitored regularly for gaps and vocabulary mismatches
768
+
769
+ ### Validation & Testing
770
+
771
+ - [ ] Tree testing shows 80%+ success rate on key tasks
772
+ - [ ] First-click accuracy is above 60% on critical navigation paths
773
+ - [ ] Usability testing has validated navigation with representative users
774
+ - [ ] Analytics confirm users can find high-priority content (low bounce, task completion)
775
+ - [ ] Accessibility audit confirms navigation meets WCAG 2.2 AA requirements
776
+ - [ ] Cross-device testing validates IA works on mobile, tablet, and desktop
777
+
778
+ ### Development Integration
779
+
780
+ - [ ] URL structure mirrors the IA hierarchy
781
+ - [ ] Application routing aligns with IA structure
782
+ - [ ] Breadcrumb structured data (schema.org BreadcrumbList) is implemented
783
+ - [ ] 301 redirects are planned for any changed URLs
784
+ - [ ] XML sitemap is generated and submitted to search engines
785
+ - [ ] Canonical URLs are set for content appearing at multiple IA locations
786
+ - [ ] Internal linking strategy distributes authority to key pages
787
+ - [ ] Navigation components are accessible (landmarks, ARIA, keyboard support)
788
+
789
+ ### Governance & Maintenance
790
+
791
+ - [ ] Content governance process requires IA placement for new content
792
+ - [ ] Taxonomy governance assigns ownership for term management
793
+ - [ ] Regular content audits are scheduled (quarterly or semi-annually)
794
+ - [ ] Orphaned content checks are automated (crawler-based)
795
+ - [ ] Search log review is scheduled (monthly minimum)
796
+ - [ ] IA documentation (site map, taxonomy, content model) is maintained as living artifacts
797
+
798
+ ---
799
+
800
+ *This module provides the foundational knowledge for evaluating, designing, and implementing information architecture across digital products. Apply these principles in conjunction with user research, content strategy, and interaction design to create structures that serve both users and organizational goals.*