Add a draft specification for pattern-matching so it is version contr…

…olled.

docs/features/local-functions.md

@@ -1,3 +1,21 @@
+Local Functions
+===============
+
+This feature is to support the definition of functions in block scope.
+
+Local functions may use variables defined in the enclosing scope. The current implementation requires that every variable read inside a local function be definitely assigned, as if executing the local function at its point of definition. Also, the local function definition must have been "executed" at any use point.
+
+After experimenting with that a bit (for example, it is not possible to define two mutually recursive local functions), we've since revised how we want the definite assignment to work. The revision (not yet implemented) is that all local variables read in a local function must be definitely assigned at each invocation of the local function. That's actually more subtle than it sounds, and there is a bunch of work remaining to make it work. Once it is done you'll be able to move your local functions to the end of its enclosing block.
+
+The new definite assignment rules are incompatible with inferring the return type of a local function, so we'll likely be removing support for inferring the return type.
+
+Unless you convert a local function to a delegate, capturing is done into frames that are value types. That means you don't get any GC pressure from using local functions with capturing.
+
+We don't have a spec yet, but the feature is fairly straightforward.
+
+--------------------
+
+Below is a checklist of work on the feature
 - [ ] Parser ambiguity research
 	- Some thought done, not complete
 	- Currently thought to be unambiguous past the parameter list (starting at `{` or `=>`), but that requires lots of lookahead.